#tkn pac Command Reference

tkn pac is the official CLI plugin for Pipelines-as-Code. It automates one-off setups (creating the Repository resource, registering the webhook, generating a starter .tekton/pipelinerun.yaml) that are otherwise done manually with kubectl apply and the Git provider's web UI.

This page is a command reference for users who prefer the CLI workflow. For the recommended end-to-end procedure that uses plain manifests, see Configure GitHub Repository and Configure GitLab Repository.

#Prerequisites

• tkn CLI installed
• tkn pac plugin installed
• kubectl configured to access your cluster
• PAC component deployed

#Installing tkn pac Plugin

Download tkn from Tekton CLI Releases, then install the pac plugin from tkn pac Releases.

Install tkn pac by using one of the methods in the official tkn pac project release guide, and make sure the executable is available in your PATH.

#Verify Installation

# Verify tkn CLI
tkn version

Example output:

Client version: 0.43.0
Pipeline version: v0.65.0

# Verify tkn-pac plugin
tkn pac version

Example output:

0.39.2

#Repository Commands

#tkn pac create repository

Creates a new Pipelines as Code repository and namespace based on the pipeline run template.

Basic Syntax:

tkn pac create repo

Interactive Mode:

The command will prompt you for:

1. Git repository URL (auto-detected from current directory)
2. Namespace for pipelines (default: project-pipelines)
3. Git provider specific information (e.g., project ID for GitLab)
4. PAC controller URL (auto-detected)
5. Webhook secret (auto-generated)
6. Git provider access token
7. Git provider API URL (varies by provider)

What it does:

• Creates a Repository CR in your Kubernetes cluster
• Configures Git provider webhook automatically
• Creates Kubernetes Secret with Git provider credentials
• Generates .tekton/pipelinerun.yaml template in your repository

Example:

cd /path/to/your/repo
tkn pac create repo

Example output (interactive prompts):

? Enter the Git repository URL: https://gitlab.com/user/repo
? Enter the namespace where the pipeline should run (default: 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): 
✓ Repository CR created successfully
✓ Webhook configured in GitLab
✓ Secret created
✓ Template generated at .tekton/pipelinerun.yaml

For provider-specific end-to-end procedures, see Guides.

#tkn pac list

Lists all Pipelines as Code repositories and displays the last status of associated runs.

Basic Syntax:

tkn pac list

List in Specific Namespace:

tkn pac list -n <namespace>

Output Format:

REPOSITORY          NAMESPACE          URL                                    LAST RUN STATUS
my-repo            project-pipelines  https://gitlab.com/user/repo       Succeeded
another-repo       production         https://gitlab.com/user/another    Running

Options:

• -n, --namespace <namespace>: Specify namespace to list repositories (default: current kubectl context namespace)
• -A, --all-namespaces: List repositories in all namespaces
• -o, --output <format>: Output format (default, json, yaml, wide)

Example:

# List all repositories in current namespace
tkn pac list

# List repositories in specific namespace
tkn pac list -n project-pipelines

# List repositories in all namespaces
tkn pac list -A

#tkn pac repo describe

Describes a Pipelines as Code repository and associated runs.

Basic Syntax:

tkn pac repo describe <repository-name>

Options:

• -n, --namespace <namespace>: Specify namespace where the repository is located (default: current kubectl context namespace)
• -o, --output <format>: Output format (default, json, yaml)

Output Includes:

• Repository CR details
• Git provider configuration
• Webhook configuration
• Recent PipelineRun status
• Last run information

Example:

# Describe repository in current namespace
tkn pac repo describe my-repo

# Describe repository in specific namespace
tkn pac repo describe my-repo -n project-pipelines

Example output:

Repository: my-repo
Namespace: project-pipelines
URL: https://gitlab.com/user/repo
Git Provider: gitlab
Status: Ready

Recent Runs:
  - pipelinerun-abc123: Succeeded (2 minutes ago)
  - pipelinerun-def456: Running (5 minutes ago)
  - pipelinerun-ghi789: Failed (10 minutes ago)

#Generate Command

#tkn pac generate

Generates a simple PipelineRun template.

Basic Syntax:

tkn pac generate

Features:

• Automatically detects current Git information from the directory
• Uses basic language detection capability
• Adds extra tasks depending on the detected language
• Creates .tekton/pipelinerun.yaml template

Language Detection:

The command detects the project language and adds appropriate tasks:

• Python: Detects setup.py or requirements.txt, adds pylint task
• Go: Detects go.mod, adds golangci-lint task
• Node.js: Detects package.json, adds npm tasks
• Java: Detects pom.xml, adds maven tasks

Example:

# Navigate to your repository
cd /path/to/your/repo

# Generate pipeline template
tkn pac generate

Example output:

✓ Pipeline template generated at .tekton/pipelinerun.yaml

Generated Template Example:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: generated-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 generated pipeline!"

#Resolve Command

#tkn pac resolve

Executes a pipeline run as if it is owned by the Pipelines as Code service. This is useful for testing pipeline definitions locally without creating a new commit.

Basic Syntax:

tkn pac resolve -f <pipeline-file>

Options:

• -f, --file: Path to pipeline file or directory (required)
• -p, --param: Override parameter values (format: key=value)
• -o, --output: Output format (yaml, json, or default)

Resolve from File:

tkn pac resolve -f .tekton/pull-request.yaml

Resolve from Directory:

tkn pac resolve -f .tekton/

The command processes all .yaml and .yml files in the directory.

Override Parameters:

You can override default parameter values derived from the Git repository:

tkn pac resolve -f .tekton/pipelinerun.yaml \
  -p revision=main \
  -p repo_name=my-repo

Multiple Files:

You can use the -f flag multiple times:

tkn pac resolve -f .tekton/pipeline1.yaml -f .tekton/pipeline2.yaml

Auto-Detection:

When run from a source code repository, the command attempts to:

• Detect current Git information
• Automatically resolve parameters such as:
  • Current revision (commit SHA)
  • Branch name
  • Repository URL
  • Repository name

Example:

# Resolve pipeline from current directory
cd /path/to/your/repo
tkn pac resolve -f .tekton/pipelinerun.yaml

Example output:

Resolved pipeline:
- revision: abc1234
- repo_url: https://gitlab.com/user/repo
- branch: main
✓ Pipeline resolved successfully

Output Format:

The command outputs the resolved PipelineRun YAML to stdout. You can:

• Save it to a file: tkn pac resolve -f .tekton/pipelinerun.yaml > resolved.yaml

• View it directly: tkn pac resolve -f .tekton/pipelinerun.yaml

• Use it for validation: Check if variables are resolved correctly before committing

  # Resolve with custom parameters
  tkn pac resolve -f .tekton/pipelinerun.yaml \
    -p revision=feature-branch \
    -p repo_name=custom-repo

Example output:

Resolved pipeline:
- revision: feature-branch
- repo_url: https://gitlab.com/user/custom-repo
- branch: feature-branch
✓ Pipeline resolved successfully

Use Cases:

• Test pipeline definitions locally
• Debug pipeline issues without creating commits
• Validate pipeline syntax before committing
• Test parameter resolution

#Global Options

All tkn pac commands support the following global options:

• -h, --help: Show help for the command
• -v, --version: Show version information
• --kubeconfig: Path to kubeconfig file
• --context: Kubernetes context to use

#Best Practices

#1. Repository Management

• Use descriptive names: Choose clear repository names
• Organize by namespace: Group related repositories in namespaces
• Regular monitoring: Use tkn pac list to monitor repository status

#2. Pipeline Generation

• Review generated templates: Always review and customize generated pipelines
• Test locally: Use tkn pac resolve to test pipelines before committing
• Version control: Commit pipeline definitions to Git

#Troubleshooting

#Command Not Found

If tkn pac command is not found:

1. Verify installation:

   tkn pac version

   Example output:

   0.39.2

2. Check PATH: Ensure tkn-pac is in your PATH

3. Reinstall: Reinstall the plugin if needed

#Connection Issues

If commands fail to connect to the cluster:

1. Verify kubectl: Test kubectl connection
2. Check context: Verify Kubernetes context
3. Review permissions: Ensure you have required permissions

#Next Steps

• Guides - Repository setup walkthroughs
• Incoming Webhooks - Trigger pipelines via webhooks
• Manage PAC Component - PAC component management
• Common Issues - Troubleshooting guide