Creating source control management secrets

Some source control providers require authentication secrets to enable Konflux to access your repositories. This guide explains how to create and configure SCM (Source Control Management) secrets for Pipeline-as-Code integration.

If you upload a GitHub access token to a tenant namespace, Konflux won’t use the global GitHub application when accessing GitHub repositories.

Prerequisites

Creating a basic SCM host secret

Create a secret with your SCM access token by running the kubectl create command with a YAML file. This secret will apply to all repositories on the specified SCM host.

The secret must include the following labels:

  • appstudio.redhat.com/credentials: scm - identifies this as an SCM credentials secret

  • appstudio.redhat.com/scm.host: <source-control-management-host> - specifies the SCM host (e.g., gitlab.com or github.com)

The access token must be added to the stringData.password property. The username is not required and should not be set.

If you set both the username and password keys, the authentication type will be considered as basic, and a basic authentication client will be created using those credentials. This client may not work as some Source Code Management (SCM) providers consider basic authentication a deprecated login method.

 
kubectl create -f scm-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: pipelines-as-code-secret
  namespace: <YOUR NAMESPACE>
  labels:
    appstudio.redhat.com/credentials: scm
    appstudio.redhat.com/scm.host: <source-control-management-host> # for example, gitlab.com or github.com
type: kubernetes.io/basic-auth
stringData:
  password: <ACCESS TOKEN>

This secret will be used by the build service to perform builds with Pipeline-as-Code.

Adding multiple secrets with limited scope

This section extends the basic SCM host secret configuration described above. You can scope secrets to specific repositories or organizations by adding the appstudio.redhat.com/scm.repository annotation, allowing you to use different credentials for different organizations or repositories within the same namespace. You can also have multiple secrets with different labels and/or annotations.

Secret lookup mechanism

The secrets lookup mechanism searches for secrets in the following order, using the first match found:

  1. Repository-specific secret - a secret with the appstudio.redhat.com/scm.repository annotation matching the exact repository path

  2. Organization-wide secret - a secret with the appstudio.redhat.com/scm.repository annotation using a wildcard pattern (e.g., my-org/*)

  3. Host-level secret - a secret with only the appstudio.redhat.com/scm.host label matching the SCM host

Organization-wide secret

To create a secret for all repositories in an organization, add the appstudio.redhat.com/scm.repository annotation with a wildcard:

apiVersion: v1
kind: Secret
metadata:
  name: pac-my-org-secret
  namespace: <YOUR NAMESPACE>
  labels:
    appstudio.redhat.com/credentials: scm
    appstudio.redhat.com/scm.host: <source-control-management-host>
  annotations:
    appstudio.redhat.com/scm.repository: my-org/*
type: kubernetes.io/basic-auth
stringData:
  password: <ACCESS TOKEN>

Repository-specific secret

To create a secret for a specific repository:

apiVersion: v1
kind: Secret
metadata:
  name: pac-my-repo-secret
  namespace: <YOUR NAMESPACE>
  labels:
    appstudio.redhat.com/credentials: scm
    appstudio.redhat.com/scm.host: <source-control-management-host>
  annotations:
    appstudio.redhat.com/scm.repository: <repository-path> # for example, my-org/my-repo
type: kubernetes.io/basic-auth
stringData:
  password: <ACCESS TOKEN>

You can have multiple repositories listed under the appstudio.redhat.com/scm.repository annotation. Separate repository names with commas when listing them. The secret will be used for all repositories that match the specified paths.