Verifying source control management secrets

After you create or update an SCM secret in your tenant namespace, confirm that Konflux selects the right secret, that the access token is still valid, and that Pipeline-as-Code can access your repository. For creation steps, see Creating source control management secrets.

This guide applies to SCM secrets in your tenant namespace (the same namespace as your Application and Components). The secret name is not fixed; pipelines-as-code-secret is only an example.

Prerequisites

  • You have completed the steps listed in the Getting started with the CLI page.

  • You have created an SCM secret (or inherited one) in your tenant namespace.

  • You know your tenant namespace, the Component git repository URL (spec.source.gitURL), and the repository path (org/repo) and SCM host (github.com, and so on) derived from that URL.

Find which secret applies

Use label-based lookup when onboarding fails because Konflux cannot find or use an SCM secret. After onboarding succeeds, Repository CR will have secret which will be used for PaC (pipelinesascode.tekton.dev/v1alpha1). PaC reads credentials from that Secret for builds; label-based selection in the namespace no longer decides which secret is used in your pipeline runs.

When the Component is onboarded and the Repository CR references a tenant SCM secret, spec.gitProvider.secret names the Secret and key (password). You cannot change that reference on the Repository CR. To fix clone or fetch failures, update that Secret object (same metadata.name) with a valid token in password; creating a new Secret with a different name does not update Repository CR with new secret and old one will be still used.

When Pipeline-as-Code uses the cluster GitHub App for GitHub (no tenant token), spec.gitProvider on the Repository CR is unset and PaC does not use a tenant SCM secret from this guide. See the [IMPORTANT] note in Creating source control management secrets about tenant GitHub tokens versus the global GitHub application.

To see which Secret PaC uses when spec.gitProvider.secret is set:

# Optional: PaC Repository name from Component status
kubectl get component <component-name> -n <YOUR NAMESPACE> \
  -o jsonpath='{.status.pacRepository}{"\n"}'

kubectl get repository -n <YOUR NAMESPACE>
kubectl get repository <repository-name> -n <YOUR NAMESPACE> \
  -o jsonpath='{.spec.gitProvider.secret.name}{"\n"}'

If the command prints nothing, the Repository CR does not reference a tenant SCM secret (for example GitHub App authentication).

When onboarding fails

List candidates in the Component namespace:

kubectl get secrets -n <YOUR NAMESPACE> \
  -l appstudio.redhat.com/credentials=scm,appstudio.redhat.com/scm.host=<source-control-management-host>

Only secrets with both labels, type kubernetes.io/basic-auth, and non-empty data are considered.

Secret selection follows Secret lookup mechanism. Additional details:

  • Among wildcards, the longest matching path prefix wins.

  • Use at most one host-level secret (no appstudio.redhat.com/scm.repository annotation). If several host-level secrets match, random one of them is used; you cannot rely on which one is chosen.

Verify secret configuration

For an onboarded Component with spec.gitProvider.secret on the Repository CR, check that Secret. While onboarding is failing, check the secret that label-based lookup would select.

  • Same namespace as the Application and Component.

  • Labels appstudio.redhat.com/credentials: scm and appstudio.redhat.com/scm.host match the Component git URL host.

  • Secret type is kubernetes.io/basic-auth (not Opaque type or another type).

  • Token in the password key only (not a custom key such as token; do not set username—see Creating a basic SCM host secret).

  • If present, appstudio.redhat.com/scm.repository matches the Component repository path (exact, wildcard, or intentionally omitted for host-level scope).

  • Non-empty data; use kubectl describe secret <secret-name> -n <YOUR NAMESPACE> to confirm the password key is present. You can also use kubectl get secret <secret-name> -n <YOUR NAMESPACE> if you prefer; avoid kubectl get secret -o yaml if you do not want the token value in your terminal.

Verify the token

Test the token in password against your SCM provider for the same org/repo as the Component.

  1. Load the token from the Secret password key.

  2. Call the provider API.

GitHub

For this example, export GITHUB_TOKEN=<token>.

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer ${GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<org>/<repo>"

  • 401 — invalid, expired, or revoked token.

  • 403, or 404 on a private repository you should access — insufficient permission or scopes.

For GitLab or Forgejo, use that provider’s API and token scopes from the creation guide.

Verify Pipeline-as-Code access

When configuration and token checks pass but git access still fails, check end-to-end access as follows.

During onboarding or when the push pipeline is re-triggered

The Component status shows a git credential error only during onboarding, or when the push pipeline is re-triggered. Inspect status.message in the UI or with the CLI:

kubectl get component <component-name> -n <YOUR NAMESPACE> \
  -o jsonpath='{.status.message}{"\n"}'

When build pipelines fail on clone or fetch

If the token expires or is revoked, build pipelines fail on the clone task and the Component status does not show a git credential error. Inspect the failing PipelineRun logs, verify that the secret set on the Repository CR in spec.gitProvider.secret exists and has a valid token (see Find which secret applies), update that Secret if needed, and trigger a new run (push or /retest per Running build pipelines).

After you rotate a secret

  1. Update the Secret in your tenant namespace (new password value). If the Component is onboarded and the Repository CR has spec.gitProvider.secret, use the same metadata.name as that reference. If onboarding is still failing, update the secret that label-based lookup would select. Do not rely on creating a differently named Secret to change which credential PaC uses after onboarding.

  2. Repeat Verify the token, then trigger a new build (push or /retest per Running build pipelines).

Troubleshooting

Symptom Likely cause What to do

Git credential secret not found (or no SCM secret matched)

Missing or wrong labels, wrong scm.host, wrong Secret type, empty data, or repository annotation does not match (usually during onboarding)

When onboarding fails and Verify secret configuration

Invalid or unrecognized token; API returns 401

Expired, revoked, or wrong token in password

Verify the token; After you rotate a secret if you updated the credential

API returns 403 or 404 for a repository you should access

Token is valid but lacks scopes or repository permission

Verify the token; adjust PAT scopes per Creating SCM secrets — Prerequisites

Token in wrong key or wrong Secret type (for example Opaque type, or token not under password)

Build Service ignores the Secret or cannot read credentials

Verify secret configuration

API check succeeds but clone or fetch fails in a PipelineRun

Onboarded Component: token in the Secret named on the Repository CR is wrong or expired. During onboarding: another secret won label-based selection, or the Secret was not updated after rotation

Onboarded Component: When build pipelines fail on clone or fetch. During onboarding: When onboarding fails and Verify secret configuration

Component stuck in PaC provisioning (non-git-credential errors)

Image repository, container image, or other onboarding issues

Troubleshooting Components