Onboarding a component from GitLab

Create components from GitLab repositories using the Konflux UI or 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 with the UI

Prerequisites:

Enabled build pipelines for your instance of Konflux.
Enabled image controller for your instance of Konflux.
An existing application in your namespace.

Procedure

In the Konflux UI, go to the Applications page.
Click on the name of the application that you want to add a component to.
Click on Actions and Add component.
If a source control secret does not already exist for the repository or the host, click Add secret in the Build time secret section at the bottom of the page and complete the following fields:
1. Set Secret type to Source secret.
2. Enter a unique name for the secret (for example, pac-gitlab).
3. Set Authentication type to Basic authentication.
4. Enter the hostname of your GitLab instance in the Host field (for example, gitlab.com).
5. (Optional) Enter the repository path in the Repository field to scope the secret to a specific repository (for example, org/project). Leave empty to apply the secret to all repositories on the host.
6. Leave the Username field empty.
7. Enter your access token in the Password field. See Creating a GitLab access token and secret for instructions on how to acquire an access token.
8. Click Create.
Enter the URL for the git repository.
(Optional) After clicking out of the repository URL, expand the Show advanced Git options.
1. Enter the branch name to the Git reference dialog.
2. Enter the path to the context directory if the build context is contained somewhere other than the repository root.
3. Select gitlab from the Git provider annotation drop-down menu.
4. Enter the base URL of your GitLab instance in the Git url annotation field (for example, https://gitlab.com).
Enter the path to the Dockerfile within the git repository. This will be the path within the context directory.
(Optional) Change the component name if desired.
(Optional) Click on the Pipeline drop down box and select the desired pipeline to configure your component with.
(Optional) Click on Add secret to add any additional secrets needed for the component build. See creating secrets for more information.

Click Add component.

When a component is immediately removed after creation, it might result in an orphaned ImageRepository whose ownership was not yet assigned to the component. When trying to create a component again with the same name, the UI will report an error that the ImageRepository already exists. To resolve this, remove the ImageRepository manually from OCP.

Creating a component with the CLI

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	Use the `gitlab` value.
4	Configure with the provider URL.
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.

You can also set the 'build.appstudio.openshift.io/request' annotation to 'configure-pac-no-mr'. If you use this value, a merge request is not created during onboarding, and you must create the 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, see the PipelinesAsCode documentation.

After the pull request is created, a build pipeline starts. 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.