Installing on OpenShift

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.

Prerequisites

• cluster-admin permissions

Setup

1. Clone the repository:

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

2. 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 OpenShift Konflux CR and waits for all components to reach Ready

What gets deployed

Dependencies

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

Operator and Konflux

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-openshift.yaml by default. That CR contains no demo users and disables the Dex password database. Users sign in with their existing cluster credentials through the OpenShift OAuth server, which the operator configures automatically on OpenShift.

In OpenShift CI (Prow), OPENSHIFT_CI=true selects operator/config/samples/konflux-openshift-e2e.yaml instead: the same passwordless OpenShift login, with image-controller and PaC webhook TLS skip that the e2e suite needs. That file still has no Dex demo users.

To use a different CR, set KONFLUX_CR before running the script:

KONFLUX_CR=operator/config/samples/konflux-with-github-auth.yaml ./deploy-konflux-on-ocp.sh

The script refuses to apply any CR containing staticPasswords. If you are working on a deliberately throwaway cluster and accept the exposure, override it:

ALLOW_DEV_STATIC_PASSWORDS=true ./deploy-konflux-on-ocp.sh

See Examples for alternative sample configurations and the OIDC configuration guide for connecting GitHub, Google, or LDAP.

To swap the CR 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