#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. See Centralized webhook registration token.

#Step 2: Create the Kubernetes Secret

Create one Secret carrying the GitLab token and a webhook secret. Follow Create a Git Secret for PAC.

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
    secret:
      name: gitlab-webhook-config
    webhook_secret:
      name: gitlab-webhook-config

For self-hosted GitLab, set spec.url to the project URL and add git_provider.url with 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

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

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.

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"

#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. A 200 response confirms the controller received and accepted the event.

#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.

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:

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

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

#Troubleshooting

For the full troubleshooting matrix, see Common Issues.

#Next steps

• Define PipelineRuns in Git — define and evolve pipelines under .tekton/.
• Trigger PAC Pipelines — automatic events and comment commands.
• Advanced Repository Configuration — concurrency, parameters, custom settings.
• Configure Custom Certificates — for self-hosted GitLab with a private CA.