Configure GitLab Repository

This guide connects a GitLab repository to PAC: prepare the credentials, create the Repository resource, let the controller register the webhook, and trigger a PipelineRun.

GitLab uses Webhook mode. A GitLab access token and a project webhook are required. When automatic webhook registration is enabled, the webhook registration controller creates or updates the project webhook for you.

This page uses manifests and the GitLab Web UI. For the CLI workflow, see tkn pac Command Reference.

Prerequisites

  • PAC component deployed and exposed to GitLab; see Manage PAC Component.
  • The PAC webhook URL is recorded in pipelines-as-code-info.data.controller-url. See Get the PAC Webhook URL for setup and verification.
  • Maintainer access to the GitLab project, or a token with permission to manage project webhooks.
  • A target Kubernetes namespace where the Repository resource and its PipelineRuns will live.
  • kubectl access to that namespace.

Step 1: Create a GitLab Access Token

PAC needs a token to read project metadata, post merge request comments, and update commit status. A Personal Access Token or a Project Access Token both work.

  1. In GitLab, open the project or your user Settings → Access Tokens.
  2. Create a token with:
    • Name: a descriptive name, for example pac-integration.
    • Scopes: api.
  3. Copy the token. GitLab shows it only once.

This Repository-local token is used by PAC during normal pipeline processing. It does not need Maintainer/Owner access solely for webhook registration when a centralized webhook registration credential is configured.

For automatic webhook registration, configure a matching centralized credential with the api scope. The token identity must be an instance administrator or have Maintainer/Owner access to the target project. The credential is a Secret in the webhook registration controller namespace (tekton-pipelines in the default installation); creating it needs write access to Secrets there, usually a cluster administrator. See Centralized webhook registration token.

Step 2: Create the Kubernetes Secret

Create one Secret carrying the GitLab token and a webhook secret. Follow Step 2 and Step 3 of Create a Git Secret for PAC, and create the Secret as gitlab-webhook-config in the namespace project-pipelines: use these names for <secret-name> and <your-namespace>, or for metadata.name and metadata.namespace in the manifest.

In the rest of this guide the Secret is named gitlab-webhook-config.

Step 3: Create the Repository resource

The Repository references the Secret. For GitLab.com:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://gitlab.com/<group>/<project>
  git_provider:
    type: gitlab
    url: https://gitlab.com
    secret:
      name: gitlab-webhook-config
    webhook_secret:
      name: gitlab-webhook-config

For self-hosted GitLab, set spec.url to the project URL and git_provider.url to the GitLab instance base URL:

spec:
  url: https://gitlab.example.com/<group>/<project>
  git_provider:
    type: gitlab
    url: https://gitlab.example.com
    secret:
      name: gitlab-webhook-config
    webhook_secret:
      name: gitlab-webhook-config
INFO

For self-hosted GitLab, git_provider.url must be the GitLab instance base URL, not the project URL. Without git_provider.url, PAC can report the final status of a run to https://gitlab.com with the Repository's token.

Save the Repository manifest as repository.yaml and apply it:

kubectl apply -f repository.yaml

Verify:

kubectl get repositories -n project-pipelines

Example output:

NAME      URL                                       SUCCEEDED   REASON   STARTTIME   COMPLETIONTIME
my-repo   https://gitlab.com/group/project

Step 4: Verify automatic webhook registration

After the Repository is created, the webhook registration controller watches it and registers a GitLab project webhook. Check the Repository annotations and events:

kubectl describe repository my-repo -n project-pipelines
kubectl get repository my-repo -n project-pipelines \
  -o jsonpath='{.metadata.annotations.pac\.tekton\.alauda\.io/webhook-registration-status}'

Expected status is Registered. The controller creates or updates a GitLab webhook with:

  • URL: the public PAC webhook URL
  • Secret token: the webhook.secret value referenced by spec.git_provider.webhook_secret
  • Events: push, tag push, comments, and merge requests
  • SSL verification: enabled by default

Automatic registration is configured by tektoncd-enhancement-controller. See Configure Enhancement Features via TektonConfig for pac-webhook-registration.* settings, including provider-side TLS verification. If the GitLab API uses a private CA, also follow Configure Custom Certificates for the controller trust configuration.

The controller records the GitLab hook ID in pac.tekton.alauda.io/webhook-managed-ref. If the PAC webhook URL changes later, the controller updates the recorded hook by ID instead of creating a duplicate hook for the same project.

INFO

The controller uses the token from spec.git_provider.secret first. Keep that Repository-local token scoped for normal PAC access. If it is missing or lacks webhook management permission, the controller can use one matching labeled credential Secret in the webhook registration controller namespace. The centralized GitLab credential needs the api scope, and the token identity must be an instance administrator or have Maintainer/Owner access to the target project. See Create a Git Secret for PAC.

To exclude one Repository from automatic webhook registration, add this label to the Repository metadata:

metadata:
  labels:
    pac.tekton.alauda.io/webhook-registration-disabled: "true"

If the controller has already registered a webhook for this Repository, adding the label deletes that webhook from the GitLab project. After the controller has processed the label, the pac.tekton.alauda.io/webhook-registration-status annotation is Skipped and pac.tekton.alauda.io/webhook-registration-reason is RepositoryOptOut. Register it again by hand as described in Manual fallback if the project still needs to send events to PAC.

Manual fallback

If automatic registration is disabled or cannot be used, register the webhook manually:

  1. Open the GitLab project, then Settings → Webhooks.
  2. Click Add new webhook.
  3. Fill in the form:
    • URL: the PAC webhook URL from the prerequisites.
    • Secret token: the same webhook.secret value stored in the Kubernetes Secret.
    • SSL verification: enabled (recommended; uncheck only for non-production setups with self-signed certificates).
  4. Under Trigger, check:
    • Push events (with All branches unless you want to restrict)
    • Tag push events
    • Comments
    • Merge request events
  5. Click Add webhook.

GitLab offers a Test → Push events action under the webhook entry. PAC answers with HTTP 202 and the body {"status":202,"message":"accepted"}. This only shows that the controller received the request: PAC checks the secret token and matches the .tekton/ PipelineRuns after it replies, so a wrong secret token also gets 202. Check the result with kubectl get pipelineruns and in the PAC controller log, as described in Verification.

Step 5: Add a PipelineRun and trigger it

Add a PipelineRun manifest under .tekton/ in the repository and push it. PAC reads the file from the branch the event was raised on, matches the annotations against the event, and creates a PipelineRun in the namespace. With pipelinerun_provenance: default_branch instead of the default source, PAC reads the file from the branch whose name is the repository's default branch (for example main), whichever branch a merge request comes from; see Source Branch Configuration.

See Define PipelineRuns in Git for the file layout and annotation grammar, and Trigger PAC Pipelines for automatic and comment-based triggers.

Verification

After a Git event arrives, PAC creates a PipelineRun in the Repository's namespace. Confirm:

kubectl get pipelineruns -n project-pipelines \
  -l pipelinesascode.tekton.dev/repository=my-repo

The PAC controller logs show the event being processed. Reading them needs read access to Pod logs in the PAC namespace, usually a cluster administrator. With -l, kubectl logs prints only the last 10 lines unless --tail is set, so the commands below read 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 no PipelineRun appears, check the controller log for a webhook secret mismatch. PAC does not reject a request with a wrong secret token; it answers 202, logs an error, and creates no PipelineRun. PAC records an event on the Repository for this error only when the webhook.secret value stored in the Kubernetes Secret contains a newline or a space: the event RepositorySecretValidation, with a hint about that character. For any other wrong token, the error is not recorded as an event on the Repository, so only someone who can read Pod logs in the PAC namespace sees it:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --since=10m --tail=-1 | grep "check your webhook secret"

Example output (only the message shown):

an error occurred: client setup failed: could not validate payload, check your webhook secret?: gitlab webhook validation failed: token does not match configured secret

GitLab displays the commit status set by PAC on the relevant pipeline / merge request page.

Troubleshooting

SymptomFirst thing to check
Webhook test succeeds (HTTP 202) but no PipelineRun appearsThe controller log has no webhook secret error (see Verification and the secret token row below). Then: a PipelineRun manifest exists under .tekton/ and its annotations match the event. See Define PipelineRuns in Git.
Webhook test fails with connection refusedThe PAC webhook URL is reachable from GitLab. See Get the PAC Webhook URL.
Webhook test succeeds (HTTP 202), no PipelineRun appears, and the controller log shows could not validate payload, check your webhook secret?: gitlab webhook validation failed: token does not match configured secretThe Secret token of the GitLab webhook matches the webhook.secret value in the Kubernetes Secret. PAC does not reject a wrong token with 401 or 403: it accepts the request, logs this error, and creates no PipelineRun.
Webhook test succeeds (HTTP 202), no PipelineRun appears, and the controller log shows could not validate payload, check your webhook secret?: no webhook secret configured: set webhook secret in repository CR or secretThe Repository references the Kubernetes Secret that holds the webhook secret in git_provider.webhook_secret. Without a webhook secret, PAC drops every GitLab webhook event for the Repository; requests to the incoming webhook endpoint do not use the webhook secret. See Create the Git Secret.
Webhook test succeeds (HTTP 202), no PipelineRun appears, and the controller log shows could not validate payload, check your webhook secret?: no X-Gitlab-Token header detected: webhook validation requires a token for securityThe GitLab webhook sends no Secret token. First check that the Repository references the Kubernetes Secret that holds the webhook secret in git_provider.webhook_secret: with automatic registration, the controller then sets the webhook's Secret token from it. For a webhook added by hand, set its Secret token to the webhook.secret value in the Kubernetes Secret.
Repository annotation webhook-registration-status=FailedRun kubectl describe repository <name> -n <ns> and check pac.tekton.alauda.io/webhook-registration-reason. Common causes are a missing Secret or an empty key referenced by git_provider.webhook_secret (reason MissingWebhookSecret), missing token, insufficient token permission, wrong git_provider.url (reason InvalidRepository when it is the project URL), or untrusted certificates. A ProviderAPIError with status 404 or 405 on a hook URL means that the GitLab project was moved, renamed, or scheduled for deletion; point spec.url at the current project path.
Self-hosted GitLab: the webhook test succeeds (HTTP 202) but no PipelineRun appears, and the controller log shows failed to list .tekton dir: Get \"https://<gitlab-host>/<group>/<project>/api/v4/...; or the Repository has pac.tekton.alauda.io/webhook-registration-reason=InvalidRepository with the message GitLab repository path is emptygit_provider.url is the GitLab instance base URL (for example https://gitlab.example.com), not the project URL. PAC appends /api/v4 to git_provider.url, so a project URL sends its GitLab API calls to a wrong path, and automatic webhook registration fails.
Status checks are not posted back to GitLabThe token has the api scope and has not expired. The Repository events show the error; events are kept only for a limited time, so check soon after the event: kubectl get events -n <ns> --field-selector involvedObject.kind=Repository lists FailedToSetCommitStatus with 403 {error: insufficient_scope} for a token without the api scope, or with POST https://gitlab.com/api/v4/projects/<id>/statuses/<sha> for a self-hosted GitLab when the Repository has no git_provider.url.

For the full troubleshooting matrix, see Common Issues.

Next steps