Onboarding a component from GitLab with the CLI

Create components from GitLab repositories using kubectl.

Prerequisites

Enabled build pipelines for your instance of Konflux.
kubectl CLI tool
You have completed the steps listed in the Getting started with the CLI page.
An existing application in your namespace.

Creating a GitLab access token and secret

Before onboarding a component from GitLab, you must create a source control secret to enable Konflux to access your GitLab repository.

Procedure

In GitLab click on Settings → Access Tokens on the left menu of your repository.

If you do not see this option, ask a user with repository maintainer permissions to create the token.
Click on Add new token.
If your GitLab instance supports setting token roles, set the role to Maintainer.
Select the following scopes: api, read_repository, and write_repository.
Click Create project access token and copy the generated token.
Create a secret in your Konflux tenant namespace. See Creating source control management secrets for detailed instructions on creating the secret with the token.

This Project Access Token is scoped to a project, so you cannot use it to access resources from other projects. For more information regarding Project Access Tokens, see the GitLab documentation.
If your GitLab project uses restrictive push rules to verify users, Konflux may fail to push commits to your repository.

Creating a component

Create a Component.yaml file locally.

Example Component.yaml object

apiVersion: appstudio.redhat.com/v1alpha1
kind: Component (1)
metadata:
  name: <component-name>
  namespace: <namespace>
  annotations:
    build.appstudio.openshift.io/request: configure-pac
    build.appstudio.openshift.io/pipeline: '{"name":"<name-of-the-pipeline-to-use>","bundle":"latest"}' (2)
    git-provider: gitlab (3)
    git-provider-url: https://gitlab.com (4)
spec:
  application: <owning-application-name> (5)
  componentName: <component-name>
  source:
    git:
      url: https://gitlab.com/your-org/your-repo.git (6)
      revision: main (7)
      context: ./ (8)
      dockerfileUrl: Containerfile (9)
  containerImage: <oci-repository-to-push-image-to> (10)

1	A component is required to map to a git repository to build.
2	Optional: If used, it should point to a configured pipeline. If not specified, the default configured pipeline will be used.
3	Optional: Use if you are building a component from GitLab.
4	Optional: Configure with the provider URL if you are building a component from GitLab.
5	Each component belongs to one application. That application should be defined in the same file if it does not already exist.
6	URL for the source repository. This MUST use the `https://[…]` format for cloning a repository.
7	Optional: Branch to build in the repository. If not specified, the default branch will be used.
8	Optional: The context to build within the git repository. If not specified, the default defined in the configured pipeline will be used.
9	Optional: Path to the Containerfile within the context. If not specified, the default value of "Dockerfile" will be used.
10	Optional: If the image controller is not deployed, this is required. You must create a registry secret that has permissions to push and pull for the specified path. If an ImageRepository is created, this should be omitted.

Request annotation 'build.appstudio.openshift.io/request' can be set also to 'configure-pac-no-mr' and then during onboarding the onboarding MR won’t be created and users will have to create pipeline run yaml files for the component manually.

Create an ImageRepository.yaml file locally.

Example ImageRepository.yaml object

apiVersion: appstudio.redhat.com/v1alpha1
kind: ImageRepository (1)
metadata:
  annotations:
    image-controller.appstudio.redhat.com/update-component-image: 'true'
  name: <component-name>
  namespace: <namespace>
  labels:
    appstudio.redhat.com/application: <application-name>
    appstudio.redhat.com/component: <component-name>
spec:
  image:
    name: <namespace>/<component-name>
    visibility: public (2)

1	Optional: If the `spec.containerImage` has been defined for the component, this should not be created. If the image controller is not deployed, this custom resource will have no effect.
2	Supported values are "public" and "private".

Apply the resource to your namespace by running the following command:
```
$ kubectl apply -f Component.yaml ImageRepository.yaml
```
You can create additional components by adding their custom resource configurations to the Component.yaml file. Separate multiple resources with ---:
```
# Component A
---
# Component B
```

Configure the build pipeline for your component:

If the annotation build.appstudio.openshift.io/request: configure-pac is set on the component, Konflux automatically creates a merge request in your repository with the Tekton pipeline definitions. Review and merge this merge request to complete the setup.
If the annotation is not set or is set to configure-pac-no-mr, manually create or update the Tekton pipeline files in your repository.

The PipelineRun will run only for submitters who have permission to run PipelineRuns or who receive an /ok-to-test comment from an authorized user.
For further details on PipelineRun permissions, please refer to the PipelinesAsCode documentation.

Once the merge request is made, a build pipeline should start. Track its progress in the Konflux UI or see the final status in GitLab after the pipeline completes. If the pipeline is successful, merge the merge request.