#Configure GitLab Repository

This guide explains how to configure a GitLab repository to work with PAC, enabling pipelines to be triggered from GitLab events.

#Prerequisites

Before configuring a GitLab repository, ensure you have:

• PAC component deployed and running (see Manage PAC Component)
• PAC controller exposed and accessible (via Ingress or NodePort)
• tkn CLI installed with pac plugin
• GitLab repository with repo-scope admin access
• GitLab Personal Access Token with appropriate scopes

#Overview

The tkn pac create repo command is the recommended way to configure a GitLab repository for PAC. It automates the entire setup process:

1. Creates a Repository CR in your Kubernetes cluster
2. Configures GitLab webhook automatically
3. Creates Kubernetes Secret with GitLab credentials
4. Generates a basic .tekton/pipelinerun.yaml template in your repository

#Step 1: Install tkn pac Plugin

Ensure you have the tkn pac plugin installed:

tkn pac version

If not installed, follow the installation guide in tkn pac Command Reference.

#Step 2: Prepare GitLab Access Token

You need a GitLab Personal Access Token with the following scopes:

• api: Full API access

#Create Personal Access Token

1. Go to GitLab → User Settings → Access Tokens (or Project Settings → Access Tokens for project tokens)
2. Create a new token with:
   • Name: PAC Integration (or any descriptive name)
   • Scopes: Select api
   • Expiration date: Set as needed (optional)
3. Click Create personal access token
4. Copy the token immediately - it won't be shown again

#Store Token Securely

Save the token in a secure location. You'll need it when running tkn pac create repo.

Security Best Practice: Consider using a project token instead of a personal token for better access control.

#Step 3: Get PAC Controller URL

Before configuring the repository, you need the PAC controller URL. This URL is used by GitLab to send webhook events to PAC.

#Method 1: Query Ingress (if configured)

Check if PAC controller is exposed via Ingress (replace <pac-namespace> with your PAC namespace, default is tekton-pipelines):

kubectl get ingress -n <pac-namespace> | grep pipelines-as-code

Example output (if Ingress is configured):

NAME                  CLASS    HOSTS              ADDRESS        PORTS   AGE
pipelines-as-code     nginx    pac.example.com    192.168.1.10   80      5m

If found, get the Ingress host:

kubectl get ingress pipelines-as-code -n <pac-namespace> -o jsonpath='{.spec.rules[0].host}'

Example output:

pac.example.com

The controller URL will be:

• HTTP: http://<ingress-host>
• HTTPS: https://<ingress-host>

#Method 2: Query NodePort Service (if configured)

Check if PAC controller is exposed via NodePort (replace <pac-namespace> with your PAC namespace, default is tekton-pipelines):

kubectl get svc -n <pac-namespace> pipelines-as-code-controller-nodeport

Example output (if NodePort is configured):

NAME                                      TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
pipelines-as-code-controller-nodeport    NodePort   10.96.123.45    <none>        8080:30080/TCP   5m

If found, get the NodePort and node IP:

# Set your PAC namespace (default: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"

# Get NodePort
NODEPORT=$(kubectl get service -n ${PAC_NAMESPACE} pipelines-as-code-controller-nodeport -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

# Get Node IP
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

echo "PAC Controller URL: http://${NODE_IP}:${NODEPORT}"

Example output:

PAC Controller URL: http://192.168.1.100:30080

#Method 3: Query LoadBalancer Service (if configured)

Check if PAC controller is exposed via LoadBalancer (replace <pac-namespace> with your PAC namespace, default is tekton-pipelines):

kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer

Example output (if LoadBalancer is configured):

NAME                                      TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)          AGE
pipelines-as-code-controller-lb          LoadBalancer   10.96.123.45    192.168.1.200   8080:30080/TCP   5m

If found, get the service name and external IP:

# Get the service name first
SERVICE_NAME=$(kubectl get svc -n <pac-namespace> | grep pipelines-as-code-controller | grep LoadBalancer | awk '{print $1}')

# Get the external IP
kubectl get svc -n <pac-namespace> ${SERVICE_NAME} -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Example output:

192.168.1.200

#Automatic Detection by tkn pac

The tkn pac create repo command can automatically detect the controller URL by checking:

1. Ingress resources
2. LoadBalancer services
3. NodePort services

If automatic detection fails, you can manually enter the URL when prompted.

#If You Cannot Find the URL

If none of the above methods work or you don't have permission to query cluster resources:

1. Contact your PAC administrator to get the PAC controller URL
2. The administrator can find it using the methods in Manage PAC Component
3. The URL format is typically: http://<host-or-ip>:<port> or https://<host-or-ip>

#Step 4: Configure Repository with tkn pac

#Navigate to Your Repository

Clone or navigate to your GitLab repository:

cd /path/to/your/gitlab-repo

#Run tkn pac create repo

Important: Navigate to your GitLab repository directory before running the command. The .tekton directory will be created in the current working directory.

cd /path/to/your/gitlab/repo
tkn pac create repo --pac-namespace tekton-pipelines

Note: If PAC is installed in a different namespace, adjust the --pac-namespace parameter accordingly. Replace tekton-pipelines with your actual PAC namespace if you deployed PAC in a different namespace. The --pac-namespace parameter specifies where the PAC controller is deployed (default: tekton-pipelines).

#Interactive Configuration

The command will prompt you for the following information:

#1. Git Repository URL

? Enter the Git repository URL: 

• Default: Auto-detected from current directory's git remote
• Format: https://gitlab.com/username/repo or git@gitlab.com:username/repo
• Action: Press Enter to use default, or enter a different URL

#2. Namespace for Pipelines

? Enter the namespace where the pipeline should run (default: default): 

• Default: default
• Description: Kubernetes namespace where PipelineRuns will be created
• Action: Enter your preferred namespace (e.g., project-pipelines), or press Enter to use default

Important:

• The namespace must exist before PAC can create PipelineRuns in it

• If the namespace doesn't exist, create it first:

  kubectl create namespace <your-namespace>

  Example:

  kubectl create namespace project-pipelines

• It's recommended to use a dedicated namespace like project-pipelines instead of default

• The namespace must have RBAC permissions for PAC to create resources

#3. GitLab Project ID

? Enter the GitLab project ID: 

• How to find:
  • Go to your GitLab project → Settings → General
  • Find "Project ID" under "Project information"
  • Or use the API: curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/projects?search=<repo-name>"

#4. PAC Controller URL

? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 

• Default: Auto-detected from cluster resources
• Action:
  • If auto-detected correctly, press Enter
  • If not detected, enter the URL manually
  • If you don't know the URL: See Step 3: Get PAC Controller URL above for query commands, or contact your PAC administrator

#5. Webhook Secret

? Enter the webhook secret (default: auto-generated): 

• Default: Auto-generated random string
• Description: Secret used to validate webhook requests from GitLab
• Action: Press Enter to use default, or enter a custom secret

Security: Keep this secret secure. It's stored in the Kubernetes Secret.

#6. GitLab Access Token

? Enter the GitLab access token: 

• Description: The Personal Access Token created in Step 2
• Action: Paste your token

#7. GitLab API URL

? Enter the GitLab API URL (default: https://gitlab.com): 

• Default: https://gitlab.com (for GitLab.com)
• For self-hosted GitLab: Enter your GitLab instance URL, e.g., https://gitlab.example.com
• Action: Press Enter for GitLab.com, or enter your instance URL

#Example Interactive Session

? Enter the Git repository URL: https://gitlab.com/myuser/myproject
? Enter the namespace where the pipeline should run (default: project-pipelines): 
? Enter the GitLab project ID: 12345678
? Enter the Pipelines as Code controller URL (default: http://pac.example.com): 
? Enter the webhook secret (default: auto-generated): 
? Enter the GitLab access token: glpat-xxxxxxxxxxxxxxxxxxxx
? Enter the GitLab API URL (default: https://gitlab.com): 

#Step 5: Verify Configuration

#Check Repository CR

First, determine your namespace (the namespace you specified when creating the Repository CR). If you don't remember, list all Repository CRs:

kubectl get repositories --all-namespaces

Example output:

NAMESPACE          NAME       URL                              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
project-pipelines  my-repo    https://gitlab.com/user/repo     True        Succeeded

Then verify the Repository CR was created in your namespace:

kubectl get repositories -n <your-namespace>

Example output:

NAME       URL                              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
my-repo    https://gitlab.com/user/repo     True        Succeeded

View the Repository CR details:

First, get the repository name from the list above, then view details:

kubectl get repository <repo-name> -n <your-namespace> -o yaml

Replace <repo-name> with the actual repository name from the list (e.g., my-repo).

Example output (abbreviated):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"

#Check GitLab Webhook

1. Go to your GitLab project → Settings → Webhooks
2. Verify a webhook was created with:
   • URL: Your PAC controller URL
   • Trigger: Push events, Merge request events, Comments
   • Secret token: The webhook secret you configured

#Check Kubernetes Secret

When using tkn pac create repo, a secret is automatically created with your GitLab credentials. Verify the secret:

kubectl get secrets -n <your-namespace>

Example output:

NAME                          TYPE     DATA   AGE
my-repo                       Opaque   2      2m

View secret details:

kubectl get secret <secret-name> -n <your-namespace> -o yaml

Replace <secret-name> with the actual secret name (typically matches your repository name).

Example output (values are base64 encoded):

apiVersion: v1
kind: Secret
metadata:
  name: my-repo
  namespace: project-pipelines
data:
  provider.token: <base64-encoded-gitlab-token>
  webhook.secret: <base64-encoded-webhook-secret>

The secret contains:

• provider.token: Your GitLab personal access token
• webhook.secret: The webhook validation secret

#Check Generated Template

Verify the .tekton/pipelinerun.yaml template was created in your repository:

cat .tekton/pipelinerun.yaml

Example output:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: simple-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from Pipelines as Code!"

#Step 6: Test the Configuration

#Test Webhook Connection

You can test the webhook from GitLab:

1. Go to GitLab project → Settings → Webhooks
2. Find your PAC webhook
3. Click Test → Push events
4. Check the webhook response

#Trigger a Test Pipeline

Create a simple commit to trigger a pipeline:

echo "test" >> README.md
git add README.md
git commit -m "Test PAC integration"
git push origin main

Check if a PipelineRun was created:

kubectl get pipelineruns -n <your-namespace>

Example output:

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   1 minute ago   25s        Succeeded

#Manual Configuration (Alternative)

If you prefer to configure manually or need more control, you can create the Repository CR and configure the webhook separately.

#Create Repository CR Manually

Create a file repository.yaml:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/myuser/myproject"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

Apply the CR:

kubectl apply -f repository.yaml

Example output:

repository.pipelinesascode.tekton.dev/my-repo created

#Create GitLab Secret

Create a secret with your GitLab token:

kubectl create secret generic gitlab-secret \
  --from-literal=token=glpat-xxxxxxxxxxxxxxxxxxxx \
  -n project-pipelines

Example output:

secret/gitlab-secret created

#Create Webhook Secret

kubectl create secret generic webhook-secret \
  --from-literal=secret=your-webhook-secret \
  -n project-pipelines

Example output:

secret/webhook-secret created

#Configure GitLab Webhook Manually

1. Go to GitLab project → Settings → Webhooks
2. Add a new webhook:
   • URL: http://pac.example.com
   • Secret token: The webhook secret from above
   • Trigger: Select "Push events" and "Merge request events"
3. Click Add webhook

#Using Private Repositories

PAC supports private GitLab repositories. To configure authentication for private repositories, see the Configure Authentication for Private Repositories guide.

This guide covers authentication methods that work across all Git providers, including:

• Personal Access Token (PAT) authentication
• SSH key authentication
• Verification steps and troubleshooting

#Interfacing with Custom Certificates

If your GitLab instance uses self-signed certificates or custom CA certificates, you need to configure PAC to trust these certificates. See the Configure Custom Certificates guide for detailed instructions.

This guide covers:

• Creating ConfigMaps with CA certificates
• Mounting certificates in PAC controller pods
• Configuring Git to use custom certificates
• Verification and troubleshooting steps

#Troubleshooting

#Check if Repository CR is Not Created

Check for errors:

kubectl describe repository <repo-name> -n <your-namespace>

Example output (abbreviated):

Name:         my-repo
Namespace:    project-pipelines
Status:       Ready
Events:
  Type    Reason   Age   From     Message
  ----    ------   ----  ----     -------
  Normal  Ready    5m    pac      Repository validated

#Check if Webhook is Not Configured

If the webhook wasn't created automatically:

1. Verify the GitLab token has api scope
2. Check the token is valid: curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/user"
3. Manually create the webhook (see Manual Configuration above)

#Check if Webhook Events are Not Received

1. Check PAC controller logs:

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100  # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)

Example output:

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Processing webhook event","repository":"my-repo","namespace":"project-pipelines"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PipelineRun created","pipelineRun":"simple-pipeline-xxxxx"}

2. Verify webhook URL is accessible from GitLab
3. Check webhook secret matches in both GitLab and Repository CR

#Check if PipelineRuns are Not Created

1. Check Repository CR:

   kubectl get repository <repo-name> -n <your-namespace> -o yaml

Example output (abbreviated):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines

2. Check PAC controller logs for errors
3. Verify .tekton/pipelinerun.yaml exists in your repository
4. Check namespace permissions

#Check if Private Repository Access Issues

1. Verify token permissions: Ensure the token has api scope
2. Check secret exists: Verify the authentication secret exists in the namespace
3. Review Repository CR: Ensure the secret is correctly referenced
4. Check PAC logs: Look for authentication errors in controller logs

For more details, see Configure Authentication for Private Repositories.

#Check if Certificate Issues

1. Verify certificate mount: Check that the certificate is mounted in the pod
2. Check certificate validity: Ensure the certificate is not expired
3. Verify Git configuration: Check that Git is configured to use the certificate
4. Review logs: Look for SSL/certificate errors in PAC controller logs

For more details, see Configure Custom Certificates.

#Next Steps

• Configure Authentication for Private Repositories - Configure authentication for private repositories
• Configure Custom Certificates - Configure custom CA certificates
• Maintain Pipeline Code - Learn how to define pipelines in your repository
• Trigger Pipelines - Learn about different trigger methods
• Common Issues - Troubleshooting guide