#tkn pac Command Reference

This guide provides a comprehensive reference for the tkn pac CLI plugin commands, including repository management, pipeline generation, and resolution.

#Prerequisites

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

#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 detailed usage, see Configure Repository.

#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

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