Originally published at: Onboarding a Forgejo-hosted project to Fedora Konflux – Fedora Community Blog
We, the Forge team, recently onboarded a Codeberg-hosted repo to the new Fedora Konflux instance.
This is a guide based on the onboarding experience, the steps and UI are similar in Fedora’s Forge.
Useful links
- Konflux UI: https://konflux-ci.fedoraproject.org
- Cluster Console: https://console-openshift-console.apps.kflux-fedora-01.84db.p1.openshiftapps.com
- Cluster API (for
oc login): https://api.kflux-fedora-01.84db.p1.openshiftapps.com:6443
Step 1: Get access to the tenants-config GitLab repo
Konflux configuration is managed through GitOps in the
tenants-config
repo on GitLab. The UI is intended to be read-only — you should do everything through merge requests.
- Sign in via SAML SSO at https://gitlab.com/groups/fedora/-/saml/sso to get
group membership. - Make sure you have at least a Guest role. Guest lets you approve MRs
but not merge them. Ask a maintainer to bump your role if needed. - Get yourself added to CODEOWNERS for your tenant’s directory
Example MR.
Step 2: Create your tenant namespace
Follow the instructions in the
tenants-config repo:
- Run the
create-tenant-resourcesplaybook. It generates the namespace, RBAC
and quota resources.
You end up with three files:
ns.yaml— the namespace with akonflux-ci.dev/type: tenantlabelrbac.yaml— a RoleBinding grantingkonflux-admin-user-actionsto your FAS
userkustomization.yaml— ties together the quota, RBAC, namespace and your
applications directory. Quota can be increased later.
Then run the update-tenant-apps playbook to generate an ArgoCD application
manifest per tenant directory and update the ArgoCD kustomization.
Step 3: Define your Applications and Components
This is where you tell Konflux what to build. We went with a Kustomize
Configuration-as-Code setup with three layers:
- A shared base — a generic Component template with the git URL, provider
annotations (git-provider: forgejo,git-provider-url: https://codeberg.org),
pipeline config and thebuild.appstudio.openshift.io/request: configure-pac
annotation. - Per-application bases — an Application CR plus per-variant overrides (e.g.
rawhide vs. stable). - Per-environment overlays (staging/production) — patches for application names,
component names, context paths and Dockerfile paths.
Open a merge request with everything
Example MR.
Step 4: Add ImageRepository resources
Each Component needs a matching ImageRepository CR. If you don’t have one, the image controller
never provisions a Quay repo, spec.containerImage stays empty on the
Component, and the build service just sits there waiting. No webhook, no PaC PR,
nothing happens.
Example ImageRepository:
apiVersion: appstudio.redhat.com/v1alpha1
kind: ImageRepository
metadata:
name: forge-rawhide-production
namespace: fedora-infra-tenant
annotations:
image-controller.appstudio.redhat.com/update-component-image: "true"
labels:
appstudio.redhat.com/application: forge-production
appstudio.redhat.com/component: forge-rawhide-production
spec:
image:
name: fedora-infra-tenant/forge-rawhide-production
visibility: publicThe update-component-image: "true" annotation is what tells the image
controller to write the Quay URL back to spec.containerImage on the Component.
Example MR. Do not merge yet.
Step 5: Create the SCM secret
Konflux needs a secret to authenticate with your Forgejo/Codeberg instance:
oc create secret generic pipelines-as-code-codeberg -n {namespace} --type=kubernetes.io/basic-auth --from-literal=password={FORGEJO_TOKEN}
oc label secret pipelines-as-code-codeberg -n {namespace}
appstudio.redhat.com/credentials=scm
appstudio.redhat.com/scm.host=codeberg.org
The Konflux docs
say you need these token scopes:
- issue: Read and Write
- organization: Read
- repository: Read and Write
- user: Read
Don’t restrict the token to a specific repo — scopes like write:user aren’t
available with repo-scoped tokens on Forgejo. If you set the right scopes and
it still complains about insufficient permissions, try a token with everything
enabled.
Step 6: Merge and verify
With the secret in place, merge your MR. ArgoCD picks it up and syncs the
resources. Wait a few minutes, then check:
# Did containerImage get set? oc get components -n {namespace} -o custom-columns='NAME:.metadata.name,IMAGE:.spec.containerImage'Are the ImageRepositories ready?
oc get imagerepositories -n {namespace}
-o custom-columns=‘NAME:.metadata.name,STATE:.status.state’What does the PaC status say?
oc get components -n {namespace}
-o custom-columns=‘NAME:.metadata.name,STATUS:.metadata.annotations.build.appstudio.openshift.io/status’
If spec.containerImage is filled in and the status shows "state":"enabled",
you’re good.
Step 7: Handle the PaC pull requests
At this point Konflux opens PRs on your source repo with auto-generated Tekton
pipeline files in .tekton/. Two ways to go:
- Merge them as-is if you’re happy with Konflux’s defaults.
- Close them and use your own pipelines. If you already have
.tekton/files,
update them with: - application/component labels matching your Konflux component names
output-imagepointing toquay.io/redhat-user-workloads/{namespace}/{component}- latest task bundle versions (grab the
@sha256:...refs from the
Konflux-generated files) serviceAccountName: build-pipeline-{component}
We went with the second option. We already had pipelines with custom version
tagging that we wanted to keep, so we pulled in the new task bundles and labels
from the generated files and left the rest alone.
Step 8: Re-triggering when things go wrong
The configure-pac annotation gets consumed on the first attempt. If it fails
(token issue, rate limit, whatever), you need to re-add it:
# One component oc annotate component {component} -n {namespace} build.appstudio.openshift.io/request=configure-pac --overwriteAll of them
for comp in $(oc get components -n {namespace} -o name); do
oc annotate $comp -n {namespace}
build.appstudio.openshift.io/request=configure-pac --overwrite
done
To sum it up, we created a tenant on Konflux-ci cluster, created applications and components and set a place where the images would be hosted. At the event of push to the codeberg repo main branch – the repo where we store the Forge Containerfiles, the pipeline gets triggered (scoped by the on-cel-expression to only those contexts where the change happened) and a fresh and tagged image appears on quay, ready for further testing and deployment.
Thanks to the Konflux Team for the Forgejo support!
