Alauda DevOps Pipelines Docs
  • English

    • 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 (read repository metadata, post commit/status checks, manage the webhook).
    • 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.

    TOC

    How PAC reads the SecretPrerequisitesStep 1: Create the Git Access TokenStep 2: Choose a Webhook SecretStep 3: Create the Kubernetes SecretStep 4: Reference the Secret from the RepositoryVerificationUpdating credentialsNext steps

    How PAC reads the Secret

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

    spec:
  git_provider:
    secret:
      name: <secret-name>
      key: provider.token       # default: provider.token
    webhook_secret:
      name: <secret-name>
      key: webhook.secret       # default: webhook.secret
    • 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.

    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.

    Step 1: Create the Git Access Token

    Create a PAT on your Git provider:

    ProviderToken typeRequired scopes
    GitHubPersonal Access Token (classic)public_repo for public repositories, repo for private repositories. Add admin:repo_hook if you intend to register the webhook with tkn pac.
    GitLabPersonal Access Token (or Project Access Token)api

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

    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:

    a4b1c2d3e4f5061718293a4b5c6d7e8f

    The webhook secret is optional but strongly recommended. Without it, anyone who learns the webhook URL can forge events.

    Step 3: Create the Kubernetes Secret

    Create one Secret that stores both values under the default keys. Replace:

    • <git-access-token> with the Git provider token from Step 1.

    • <webhook-secret> with the shared webhook secret string from Step 2.

      kubectl create secret generic <secret-name> \
  --from-literal=provider.token='<git-access-token>' \
  --from-literal=webhook.secret='<webhook-secret>' \
  -n <your-namespace>

    Example output:

    secret/my-repo-auth created

    Alternatively, create it from a manifest:

    apiVersion: v1
kind: Secret
metadata:
  name: my-repo-auth
  namespace: project-pipelines
type: Opaque
stringData:
  provider.token: glpat-xxxxxxxxxxxxxxxxxxxx
  webhook.secret: a4b1c2d3e4f5061718293a4b5c6d7e8f
    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
    secret:
      name: my-repo-auth
    webhook_secret:
      name: my-repo-auth

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

    Verification

    Confirm the Secret exists and carries both keys:

    kubectl get secret my-repo-auth -n <your-namespace> \
  -o jsonpath='{.data}' | jq 'keys'

    Example output:

    ["provider.token", "webhook.secret"]

    After the Repository resource is created, PAC logs a successful lookup. Tail the controller logs in the PAC namespace:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50

    An authentication failure ("401 Unauthorized", "invalid token") in the controller logs indicates a wrong or insufficiently-scoped token; see Common Issues for the full troubleshooting checklist.

    Updating credentials

    Rotate the token by updating the Secret in place:

    kubectl create secret generic my-repo-auth \
  --from-literal=provider.token='<new-token>' \
  --from-literal=webhook.secret='<existing-webhook-secret>' \
  -n <your-namespace> \
  --dry-run=client -o yaml | kubectl apply -f -

    PAC reads the Secret on every incoming event, so no controller restart is needed.

    Next steps