#Quick Start

#Introduction

You will:

• Create a PAC Repository connection with tkn pac
• Add a simple PipelineRun definition to the repository
• Trigger and check the first run

#Estimated Reading Time

10-15 minutes

#Prerequisites

• PAC is deployed and exposed to the Git provider network. See Manage PAC Component.
• If you use the UI to create or manage PAC Repository resources, the administrator has enabled the Repository UI feature flag. See Enable Repository UI Feature.
• The pipelines-as-code-info ConfigMap has the public PAC controller-url.
• You know the PAC namespace if you use tkn pac. The default is tekton-pipelines.
• You have the PAC webhook URL when automatic registration is disabled or fails. See Get the PAC Webhook URL.
• kubectl is configured for the target cluster.
• tkn CLI is installed with the pac plugin. See tkn pac Command Reference.
• You have administrator or maintainer access to the Git repository.

#Step 1: Configure Repository

The steps below use the tkn pac CLI and GitLab as an example. For GitHub or manifest-based setup, see Configure GitHub Repository or Configure GitLab Repository.

When a Repository has spec.git_provider.type set to github or gitlab, spec.git_provider.webhook_secret, and either a usable Repository-local provider token or a matching centralized webhook registration credential, the webhook registration controller automatically registers or updates the Git provider webhook. Repositories without a supported spec.git_provider.type are skipped, with the reason recorded as a Repository Event and status annotations.

#Confirm tkn pac Plugin

Confirm the plugin is available:

tkn pac version

Example output:

0.39.2

#Create GitLab Personal Access Token

1. Go to GitLab → Settings → Access Tokens
2. Create a token with api scope
3. Save the token securely

#Configure Repository with tkn pac

Run the command from the Git repository directory. 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

Replace tekton-pipelines if PAC was deployed in a different namespace.

Follow the interactive prompts:

1. Enter Git repository URL (auto-detected from current directory, or enter manually)
2. Enter namespace for pipelines, for example project-pipelines. The namespace must already exist.
3. Repository CR will be created at this point
4. Enter GitLab project ID (found in project settings → General)
5. Enter the PAC webhook URL if prompted. In clusters with automatic registration enabled, this URL is read from pipelines-as-code-info.
6. Enter webhook secret (or press Enter to use auto-generated default)
7. Enter GitLab access token (the Personal Access Token you created)
8. Enter GitLab API URL (default: https://gitlab.com, or enter your self-hosted GitLab URL)

The command will:

• Create the Repository resource in the selected namespace
• Configure GitLab webhook automatically
• Create Kubernetes Secret with credentials
• Generate .tekton/pipelinerun.yaml template in your repository

#Step 2: Create Your First Pipeline

The tkn pac create repo command creates a basic template at .tekton/pipelinerun.yaml. Edit it to define your pipeline:

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, pull_request]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from Pipelines as Code!"

Commit and push to your repository:

git add .tekton/pipelinerun.yaml
git commit -m "Add PAC pipeline"
git push origin <your-branch-name>

Note:

• Replace <your-branch-name> with your branch name (e.g., main, master, or develop)
• Make sure the annotation pipelinesascode.tekton.dev/on-target-branch matches your branch name. For example, if your branch is main, use "[refs/heads/main]"; if it's test, use "[refs/heads/test]"
• To match multiple branches, use comma-separated values: "[main, develop]" or "[refs/heads/main,refs/heads/develop]"
• To match all branches, use: "[refs/heads/*]"

#Step 3: Test the Pipeline

#Trigger via Push

Push a commit to the branch specified in your pipeline annotation to trigger the pipeline:

echo "test" >> README.md
git add README.md
git commit -m "Test pipeline trigger"
git push origin <your-branch-name>

#Trigger via Merge Request

Create a Merge Request to trigger the pipeline:

git checkout -b feature/test
echo "feature" >> feature.txt
git add feature.txt
git commit -m "Add feature"
git push origin feature/test

Then create a Merge Request in GitLab.

#Check Pipeline Status

View PipelineRuns in the namespace:

kubectl get pipelineruns -n project-pipelines

Example output:

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   2 minutes ago  30s        Succeeded

View pipeline logs:

# List all PipelineRuns
tkn pipelinerun list -n project-pipelines

Example output:

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   2 minutes ago  30s        Succeeded

# View logs for a specific PipelineRun
tkn pipelinerun logs <pipelinerun-name> -n project-pipelines

Example output:

[hello : echo] Hello from Pipelines as Code!

#Next Steps

• Manage PAC Component - Deploy, update, and uninstall guide
• Guides - End-to-end repository configuration walkthroughs
• Define PipelineRuns in Git - PipelineRun files and trigger annotations
• Trigger PAC Pipelines - Automatic events and comment commands