Alauda DevOps Pipelines Docs
  • English

    • tkn pac Command Reference

    For Regular Users

    This guide covers tkn pac CLI commands for repository management, pipeline generation, and resolution.

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

    TOC

    PrerequisitesInstalling tkn pac PluginVerify InstallationRepository Commandstkn pac create repositorytkn pac listtkn pac repo describeGenerate Commandtkn pac generateResolve Commandtkn pac resolveGlobal OptionsBest Practices1. Repository Management2. Pipeline GenerationTroubleshootingCommand Not FoundConnection IssuesNext Steps

    Prerequisites

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

    Installing tkn pac Plugin

    See tkn pac Releases for the latest version.

    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 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.

    What Does "Resolve" Mean?

    The resolve command processes your PipelineRun definition and:

    • Replaces PAC variables (like {{repo_url}}, {{revision}}) with actual values
    • Resolves task annotations (fetches tasks from Tekton Hub if needed)
    • Validates the pipeline structure
    • Shows you what the final PipelineRun would look like

    Important: This command does not create a PipelineRun in your cluster. It only processes and validates the pipeline definition locally.

    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