Create a Git Secret for PAC

When you integrate a repository with PAC over a Webhook (not the GitHub App), the Repository resource references a Kubernetes Secret that holds two pieces of credentials:

  • A Git access token PAC uses to call the Git provider's API during normal pipeline processing, such as reading repository metadata and posting comments or commit statuses.
  • A webhook secret the Git provider includes when delivering an event so PAC can verify the request originated from the expected source.

This guide creates that Secret for GitHub Webhook mode and GitLab Webhook mode. GitHub App mode does not need a per-repository Secret because the controller uses the cluster-wide App credentials.

How PAC reads the Secret

PAC looks up the Secret through the Repository.spec.git_provider fields:

spec:
  git_provider:
    type: gitlab                # or github
    secret:
      name: <secret-name>
      key: provider.token       # default: provider.token
    webhook_secret:
      name: <secret-name>
      key: webhook.secret       # default: webhook.secret
  • Set type to the Git provider used by this Repository, such as github or gitlab.
  • If key is omitted on secret, PAC reads provider.token.
  • If key is omitted on webhook_secret, PAC reads webhook.secret.
  • secret.name and webhook_secret.name can point to the same Secret or to two different ones.

The Secret must live in the same namespace as the Repository resource. The exception is a Repository that inherits both secret and webhook_secret from the global Repository CR: PAC then reads the token and the webhook secret from the namespace of the global Repository (the PAC namespace). Set secret and webhook_secret the same way: both in the Repository, referencing a Secret in its own namespace, or both inherited from the global Repository CR. See Behavior in Creating a Global Repository CR.

Prerequisites

  • A Git provider account with permission to create a Personal Access Token (PAT) on the repository.
  • A target namespace for the Repository resource.
  • kubectl access to that namespace.
  • The jq CLI, used in Verification.

Step 1: Create the Git Access Token

Create a PAT on your Git provider. This token is stored in the Repository namespace and is used by PAC during normal pipeline processing. Keep webhook management permissions in a centralized credential unless you intentionally want each Repository owner to store a token that can create or edit provider webhooks.

ProviderToken typeRepository-local token permissions
GitHubPersonal Access Token (classic)public_repo for public repositories, repo for private repositories. For fine-grained PATs, grant the repository permissions that the Pipelines as Code documentation lists for GitHub webhooks: Administration, Metadata and Content read-only, and Commit statuses and Pull request read and write. Do not grant Webhooks write access to this local token unless it will manage webhooks directly.
GitLabPersonal Access Token (or Project Access Token)api. PAC uses the token for actions such as reading project data, creating merge request notes, and updating commit statuses. The Repository-local token does not need Maintainer/Owner access solely for webhook registration when a centralized credential is configured.

Copy the token immediately. Most providers display it only once.

Automatic webhook registration is enabled by default (pac-webhook-registration.enabled: true in the tektoncd-enhancement-config ConfigMap; see Configure Enhancement Features via TektonConfig). While it is enabled, create a separate centralized credential with webhook management permission. Creating it needs write access to Secrets in the webhook registration controller namespace (tekton-pipelines in the default installation), usually a cluster administrator. See Centralized webhook registration token.

Step 2: Choose a Webhook Secret

The webhook secret is a shared string between PAC and the Git provider. PAC verifies incoming events against this value.

You can use any sufficiently random string, such as a generated password from your password manager. The same value must be stored in the Kubernetes Secret and configured in the Git provider webhook.

If you want to generate one from the command line, openssl is one option:

openssl rand -hex 16

Example output:

<32 hexadecimal characters, different on each run>

The webhook secret is required. PAC checks each event that the Git provider webhook sends against it before it starts a PipelineRun for the event; requests to the incoming webhook endpoint do not use it, they are checked against their own incoming secret (see Incoming Webhooks). The GitLab webhook must send the same value as its Secret token. On GitLab, PAC still answers HTTP 202 when the check fails, but it drops the event and creates no PipelineRun; which message it logs depends on whether the webhook sends a Secret token. A webhook without a Secret token gives could not validate payload, check your webhook secret?: no X-Gitlab-Token header detected: webhook validation requires a token for security; this is also the message for a Repository that does not reference a webhook secret when automatic registration created its webhook, because the controller then registers the webhook without a Secret token. A webhook that sends a Secret token to a Repository that does not reference a webhook secret gives could not validate payload, check your webhook secret?: no webhook secret configured: set webhook secret in repository CR or secret. In GitHub Webhook mode, PAC also answers HTTP 202, drops such events and creates no PipelineRun. The controller then logs a line that starts with an error occurred: client setup failed: and ends with could not validate payload, check your webhook secret?: no signature has been detected, for security reason we are not allowing webhooks that has no secret when the GitHub webhook has no secret, which is also the case when automatic registration created the webhook for a Repository that does not reference a webhook secret, or with could not validate payload, check your webhook secret?: no webhook secret has been set, in repository CR or secret when the webhook has a secret but the Repository does not reference one.

Step 3: Create the Kubernetes Secret

Create one Secret that stores both values under the default keys. Run the commands in bash or zsh: in a POSIX sh such as dash, read -rs fails and leaves the variable empty. read -rs reads a value into a shell variable without showing it, so the token and the webhook secret do not appear on the screen or in the shell history. Run each read -rs line on its own, then paste the value and press Enter: if the line is pasted together with the next lines, a shell without bracketed paste reads the next line as the value. First read the Git provider token from Step 1:

read -rs GIT_TOKEN

Then read the shared webhook secret string from Step 2:

read -rs WEBHOOK_SECRET

Then create the Secret. unset removes the variables after the Secret is created:

kubectl create secret generic <secret-name> \
  --from-literal=provider.token="$GIT_TOKEN" \
  --from-literal=webhook.secret="$WEBHOOK_SECRET" \
  -n <your-namespace>
unset GIT_TOKEN WEBHOOK_SECRET

Example output:

secret/<secret-name> created

Alternatively, create it from a manifest:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo-auth
  namespace: project-pipelines
type: Opaque
stringData:
  provider.token: <git-provider-token>
  webhook.secret: <webhook-secret>

Save the manifest as secret.yaml and apply it:

kubectl apply -f secret.yaml

Step 4: Reference the Secret from the Repository

In the Repository resource, point both git_provider.secret and git_provider.webhook_secret at the Secret you just created. Because the default keys are used, the key field can be omitted:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://gitlab.example.com/team/my-repo
  git_provider:
    type: gitlab
    url: https://gitlab.example.com
    secret:
      name: my-repo-auth
    webhook_secret:
      name: my-repo-auth

For a self-hosted GitLab, also set git_provider.url to the GitLab base URL, as in the sample; without it, PAC can report the final status of a run to https://gitlab.com with this token. For GitLab.com, set it to https://gitlab.com.

If you stored the credentials under non-default keys, set key explicitly on both fields.

Centralized webhook registration token

For automatic webhook registration, keep high-permission webhook management tokens in labeled Secrets in the webhook registration controller namespace. This is useful when Repository owners should not store a token that can create or edit provider webhooks.

The centralized Secret is only used by the webhook registration controller to register or update the Git provider webhook. PAC still reads the webhook secret from Repository.spec.git_provider.webhook_secret, so each Repository must keep that reference, set in the Repository or inherited together with secret from the global Repository CR (see How PAC reads the Secret).

The centralized token needs these permissions:

ProviderRequired webhook management permission
GitHubClassic PAT: admin:repo_hook. Fine-grained PAT: target repository Webhooks write permission.
GitLabapi scope, and the token identity must be an instance administrator or have Maintainer/Owner access to the target project.

Create exactly one matching centralized Secret for each provider type and provider URL in the webhook registration controller namespace. That is the namespace of the tektoncd-enhancement-controller Deployment, tekton-pipelines in the default installation; replace <controller-namespace> with it. Creating the Secret there needs write access to Secrets in that namespace, usually a cluster administrator:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-webhook-admin
  namespace: <controller-namespace>
  labels:
    pac.tekton.alauda.io/provider-credential: "true"
    pac.tekton.alauda.io/provider-type: gitlab
  annotations:
    pac.tekton.alauda.io/provider-url: https://gitlab.example.com
type: Opaque
stringData:
  provider.token: <token-with-webhook-management-permission>

For GitHub.com, use https://api.github.com as the provider URL. For GitHub Enterprise, use the Enterprise API URL, for example https://github.example.com/api/v3.

Example:

metadata:
  labels:
    pac.tekton.alauda.io/provider-credential: "true"
    pac.tekton.alauda.io/provider-type: github
  annotations:
    pac.tekton.alauda.io/provider-url: https://api.github.com

Matching rules:

  • The Secret must be in the namespace where the webhook registration controller runs. In the default installation this is tekton-pipelines.
  • The Secret must have pac.tekton.alauda.io/provider-credential: "true" so the controller watches it as a centralized credential.
  • provider-type must match spec.git_provider.type.
  • The pac.tekton.alauda.io/provider-url annotation is normalized before matching. For GitLab, https://gitlab.example.com and https://gitlab.example.com/api/v4 both match the same provider. For GitHub Enterprise, use the API URL, for example https://github.example.com/api/v3.
  • If multiple Secrets match the same provider, registration fails with AmbiguousCredential.
  • If spec.git_provider.secret contains a usable token, it is tried first. If that token lacks webhook management permission, the controller retries with the matching centralized Secret.

Verification

Confirm the Secret exists and that both keys hold a value:

kubectl get secret <secret-name> -n <your-namespace> \
  -o json | jq '.data | map_values(length)'

Example output, for a 26-character token and the 32-character webhook secret that the openssl command of Step 2 prints:

{
  "provider.token": 36,
  "webhook.secret": 44
}

The numbers are the lengths of the base64-encoded values. A key with 0 is empty, for example because read -rs failed in Step 3; set both values again with the commands in Updating credentials, which update the existing Secret in place. Running the kubectl create secret generic command of Step 3 again fails for an existing Secret with error: failed to create secret secrets "<secret-name>" already exists. A length above 0 does not show that the value is correct; the event check below does.

When automatic webhook registration is enabled, check the Repository right after you create it, as in Step 4 of Configure GitLab Repository or Configure GitHub Repository. If the Secret that git_provider.webhook_secret references does not exist, or the key that it references is empty, the webhook registration controller sets the pac.tekton.alauda.io/webhook-registration-status annotation to Failed and pac.tekton.alauda.io/webhook-registration-reason to MissingWebhookSecret.

PAC reads the Secret only when it processes an event for the Repository, so creating the Repository resource logs nothing about it. To check the Secret, send an event (for example, push a commit) and confirm that a PipelineRun is created and, on GitLab, that its status appears on the commit or merge request (see Configure GitLab Repository). This check needs a webhook on the project, registered automatically or by hand, and a PipelineRun under .tekton/ whose annotations match the event; without them, no PipelineRun is created even when the Secret is correct. If no PipelineRun appears, read the controller logs in the PAC namespace. This needs read access to Pod logs there, usually a cluster administrator; the missing-Secret error below is not recorded as an event on the Repository. With -l, kubectl logs prints only the last 10 lines unless --tail is set, so the command reads every line of the last 10 minutes; increase --since if the event is older:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --since=10m --tail=-1

If a Secret that the Repository references or inherits does not exist in the namespace that PAC reads it from (see How PAC reads the Secret), the log shows cannot get secret from repository: secrets "<name>" not found for the event, and no PipelineRun is created.

On GitLab, a token problem shows up in one of two ways:

  • If GitLab rejects the token (for example a wrong token), PAC creates no PipelineRun. The controller log line depends on the event. For a push event, PAC cannot read .tekton/, and the log shows failed to list .tekton dir: GET https://<gitlab-host>/api/v4/projects/<id>/repository/tree: 401 {message: 401 Unauthorized}. For a merge request event or a merge request comment, PAC first checks access to the source project, and the log shows failed to access GitLab source repository ID <id>: please ensure token has 'read_repository' scope on that repository, followed by the error that GitLab returned.

  • If the token can read the repository but lacks the api scope (for example a read_api token), PAC creates and runs the PipelineRun, but no status appears on the commit or merge request. The Repository records the event FailedToSetCommitStatus with 403 {error: insufficient_scope}, which you can see without access to the PAC namespace. Events are kept only for a limited time, so check soon after the event:

    kubectl get events -n <your-namespace> --field-selector involvedObject.kind=Repository

If a FailedToSetCommitStatus event of a self-hosted GitLab shows POST https://gitlab.com/api/v4/projects/<id>/statuses/<sha>, the Repository has no git_provider.url; set it as in Step 4.

See Common Issues for the full troubleshooting checklist.

Updating credentials

Rotate the token by updating the Secret in place. The commands below apply to one Secret that holds both values under the default keys provider.token and webhook.secret, as created in Step 3; if your Repository sets other key names or references two Secrets (see How PAC reads the Secret), use those key and Secret names in the commands instead. As in Step 3, run the commands in bash or zsh and run each read -rs line on its own, then paste the value and press Enter. First read the new token:

read -rs GIT_TOKEN

Then copy the current webhook secret from the webhook.secret key of the Secret into a variable, so that the update keeps it. The command does not show the value; it needs read access to the Secret:

WEBHOOK_SECRET=$(kubectl get secret <secret-name> -n <your-namespace> -o jsonpath='{.data.webhook\.secret}' | base64 -d)

If that key is empty (0 in Verification), read the webhook secret of Step 2 instead:

read -rs WEBHOOK_SECRET

Then update the Secret that the Repository references, and remove the variables:

kubectl create secret generic <secret-name> \
  --from-literal=provider.token="$GIT_TOKEN" \
  --from-literal=webhook.secret="$WEBHOOK_SECRET" \
  -n <your-namespace> \
  --dry-run=client -o yaml | kubectl apply -f -
unset GIT_TOKEN WEBHOOK_SECRET

On a Secret that was created with the kubectl create secret generic command of Step 3, the first kubectl apply warns that the Secret is missing the kubectl.kubernetes.io/last-applied-configuration annotation; the Secret is updated all the same, and the last output line is secret/<secret-name> configured.

Then run the checks in Verification.

PAC reads the Secret on every incoming event, so no controller restart is needed. Automatic webhook registration also reacts to changes on directly referenced Repository Secrets without requiring labels on those Secrets.

When a centralized webhook registration credential is updated, the webhook registration controller refreshes Repositories that match either the old or new provider labels and URL. If you remove the centralized credential labels or change the provider URL, existing Repositories that depended on the old credential are reconciled again and will report the current credential state.

Platform Conventions

When to enable. Apply these conventions when many repositories are onboarded to PAC in Webhook mode and each one would otherwise need its own high-permission token to create provider webhooks. A project only needs to create one Secret in its own namespace and reference it from its Repository. GitHub App mode does not use per-repository Secrets or automatic webhook registration, so these conventions do not apply to it.

Recommended values. Each Repository references a Secret in its own namespace that holds provider.token and webhook.secret: create it as in Step 3 and reference it from both spec.git_provider.secret and spec.git_provider.webhook_secret; its token has only the repository-local permissions listed in Step 1. The webhook management token is kept centrally: exactly one labeled Secret per provider type and provider URL in the webhook registration controller namespace (tekton-pipelines in the default installation), as described in Centralized webhook registration token. The controller tries the Repository token first; because that token has no webhook management permission, the controller falls back to the centralized token to register webhooks for every Repository. Optionally, a global Repository CR in the PAC namespace can hold shared git_provider settings so that a Repository declares only its url and git_provider.type. When a Repository inherits secret and webhook_secret this way, PAC reads its token and its webhook secret from the PAC namespace (tekton-pipelines in the default installation), not from the Repository's namespace (see How PAC reads the Secret), so every Repository that inherits secret uses the same token. Repositories that keep a repository-local token must set their own git_provider.secret and git_provider.webhook_secret. This feature is Technology Preview, see Creating a Global Repository CR. To confirm that registration works, check that the pac.tekton.alauda.io/webhook-registration-status annotation of each project Repository is Registered (the controller does not register the global Repository CR), as described in Step 4 of Configure GitLab Repository and Configure GitHub Repository. To stop using the centralized token, first give the token of each Repository that keeps automatic registration the webhook management permission listed in Centralized webhook registration token, then remove the pac.tekton.alauda.io/provider-credential label from the centralized Secret or delete the Secret. A Repository whose own token lacks that permission then shows Failed with the reason ProviderAPIError, and the controller keeps its existing webhook. To stop using the global Repository CR, see Stop Using the Global Repository CR.

Prerequisites. Automatic webhook registration must be enabled through tektoncd-enhancement-controller; see Configure Enhancement Features via TektonConfig for the pac-webhook-registration.* settings. The platform team needs permission to create Secrets in the webhook registration controller namespace and a provider identity that holds the webhook management permission listed in Centralized webhook registration token. If the provider API uses a private CA, the controller trust configuration from Configure Custom Certificates must be in place first.

Next steps