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.
TOC
PrerequisitesStep 1: Create a GitLab Access TokenStep 2: Create the Kubernetes SecretStep 3: Create theRepository resourceStep 4: Verify automatic webhook registrationManual fallbackStep 5: Add a PipelineRun and trigger itVerificationTroubleshootingNext stepsPrerequisites
- 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
Repositoryresource and itsPipelineRuns will live. kubectlaccess 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.
- In GitLab, open the project or your user Settings → Access Tokens.
- Create a token with:
- Name: a descriptive name, for example
pac-integration. - Scopes:
api.
- Name: a descriptive name, for example
- 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:
For self-hosted GitLab, set spec.url to the project URL and git_provider.url to the GitLab instance base URL:
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:
Verify:
Example output:
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:
Expected status is Registered. The controller creates or updates a GitLab webhook with:
- URL: the public PAC webhook URL
- Secret token: the
webhook.secretvalue referenced byspec.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.
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:
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:
- Open the GitLab project, then Settings → Webhooks.
- Click Add new webhook.
- Fill in the form:
- URL: the PAC webhook URL from the prerequisites.
- Secret token: the same
webhook.secretvalue stored in the Kubernetes Secret. - SSL verification: enabled (recommended; uncheck only for non-production setups with self-signed certificates).
- Under Trigger, check:
- Push events (with All branches unless you want to restrict)
- Tag push events
- Comments
- Merge request events
- 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:
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:
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:
Example output (only the message shown):
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.
- Configure Enhancement Features via TektonConfig — configure automatic webhook registration.