Onboarding a component from Forgejo with the CLI

Create components from Forgejo repositories using kubectl.

Forgejo support is currently in technical preview and under active development. Use this feature for testing purposes only, not in production environments.

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 Forgejo access token and secret

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

Procedure

In Forgejo, navigate to User Settings.
Click on Applications in the left menu.
In the Generate new token section, name the new token as desired.
In Select permissions, configure the following permissions:
- issue: Read and write
- repository: Read and write
Click Generate token.
Copy the generated token immediately, as it will be shown only once at the top of the screen.
Create a secret in your Konflux tenant namespace. See Creating source control management secrets for detailed instructions on creating the secret with the token.

Store the token securely after copying it, as you will not be able to view it again in Forgejo.
The access token is scoped to the permissions you selected, so ensure you have granted sufficient permissions for Konflux to interact with 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: forgejo (3)
    git-provider-url: https://codeberg.org (4)
spec:
  application: <owning-application-name> (5)
  componentName: <component-name>
  source:
    git:
      url: https://codeberg.org/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 Forgejo.
4	Optional: Configure with the provider URL if you are building a component from Forgejo.
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 pull 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 pull request in your repository with the Tekton pipeline definitions. Review and merge this pull 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 Forgejo after the pipeline completes. If the pipeline is successful, merge the pull request.