Installing on OpenShift

Deploying Konflux on an existing OpenShift cluster using the automated deployment script.

This guide covers deploying Konflux on an existing OpenShift cluster using the deploy-konflux-on-ocp.sh script. The script uses OpenShift-native components (OpenShift Pipelines, Red Hat cert-manager) instead of their upstream alternatives.

This is not the only way to install Konflux on OpenShift. You can also use:

Installing from OLM — install through the OpenShift OperatorHub
Installing from Release — apply the pre-built release bundle directly
Building and Installing from Source — build and run the operator from your local checkout

Prerequisites

Tool	Minimum version
OpenShift	v4.20
`oc` or kubectl	v1.31.4
git	v2.46
make	—
Go	v1.25.0
openssl	v3.0.13

cluster-admin permissions

Setup

Clone the repository:

git clone https://github.com/konflux-ci/konflux-ci.git
cd konflux-ci

Run the deployment script:

./deploy-konflux-on-ocp.sh

To customise the operator image or Konflux CR before running, see Script configuration.

The script performs all of the following automatically:

Deploys Konflux dependencies using OpenShift-native operators
Installs the Konflux CRDs
Deploys the Konflux Operator into the konflux-operator namespace
Waits for the Operator to be ready
Applies the default Konflux CR and waits for all components to reach Ready

What gets deployed

Dependencies

Component	Details
OpenShift Pipelines	Installed via OLM (Red Hat’s productized Tekton)
cert-manager	Installed via the Red Hat cert-manager OLM operator
trust-manager	Deployed into the `cert-manager` namespace
Kyverno	Policy engine for namespace and RBAC automation
Pipelines-as-Code	GitHub-triggered pipeline automation
Tekton Chains RBAC	RBAC for supply-chain signing using OpenShift namespaces

The following components are not deployed by deploy-deps.sh in this configuration:

Skipped	Reason
Dex	Managed by the Konflux Operator as part of the Konflux CR reconciliation
Internal OCI registry	OpenShift has its own integrated registry
Smee webhook proxy	Not needed when the cluster is internet-reachable

The script skips the Smee webhook proxy (SKIP_SMEE=true). For GitHub to deliver webhook events (triggering build pipelines on pull requests), your cluster must be reachable from the internet. If it is not, you will need to configure Smee manually after installation. See GitHub Application Secrets for details.

Operator and Konflux

Component	Details
Konflux CRDs	`Konflux` custom resource definition
Konflux Operator	Deployed in the `konflux-operator` namespace
Konflux instance	All Konflux components managed by the default sample CR

Script configuration

Operator image

By default, the script uses quay.io/konflux-ci/konflux-operator:latest. To use a different image, set OPERATOR_IMAGE before running:

OPERATOR_IMAGE=<your-registry>/konflux-operator:<tag> ./deploy-konflux-on-ocp.sh

To build and use a custom operator image from source:

cd operator
make docker-build docker-push IMG=<your-registry>/konflux-operator:<tag>
cd ..
OPERATOR_IMAGE=<your-registry>/konflux-operator:<tag> ./deploy-konflux-on-ocp.sh

Konflux Custom Resource

The script applies operator/config/samples/konflux_v1alpha1_konflux.yaml by default.

The default CR contains demo users with static passwords intended for local testing only. Never use this configuration in a production environment. Use OIDC authentication instead. See Examples for alternative sample configurations.

To use a different CR, apply it after the script completes:

kubectl delete konflux konflux
kubectl apply -f <your-konflux-cr>.yaml
kubectl wait --for=condition=Ready=True konflux konflux --timeout=15m

Verify the Konflux CR is ready

See Applying the Konflux Custom Resource for instructions on verifying the Konflux CR status and accessing the UI URL.

Create GitHub integration secrets

After the script completes, follow the GitHub Application Secrets guide to create a GitHub App and deploy its credentials into the cluster.

Uninstall

Remove the Konflux CR and all managed components:

kubectl delete konflux konflux

Remove the operator and CRDs from the operator/ directory:

cd operator
make undeploy
make uninstall

What’s next

GitHub Application Secrets — create a GitHub App and configure webhook delivery
Onboard a new Application — onboard an application, run builds, tests, and releases
Registry Configuration — configure an external container registry for build and release pipelines
API Reference — full CR field reference
Troubleshooting — solutions to common issues
Examples — sample Konflux CR configurations