Running and Managing Pipelines

Overview

Pipelines-as-Code automatically executes PipelineRuns when Git events occur (pushes, pull requests). This guide covers authorization, execution monitoring, error handling, and lifecycle management.

How Execution Works

Event Occurs

A developer pushes code or opens a pull request.

Repository Matching

PAC finds the Repository CR matching the event’s repository URL.

PipelineRun Discovery

PAC scans the .tekton/ directory for PipelineRun definitions.

Event Matching

PipelineRuns with matching annotations are selected (see Event Matching).

Authorization Check

PAC verifies the user has permission to run pipelines.

Execution

Matched PipelineRuns are created in the Repository CR’s namespace.

PipelineRuns are fetched from the source branch by default. Configure pipelinerun_provenance: "default_branch" in the Repository CR to always use the default branch.

ACL Permissions

Only authorized users can trigger PipelineRuns. A user is authorized if they are:

Repository-based
OWNERS file
OWNERS_ALIASES
Repository CR Policy

Repository owner
Repository collaborator
Organization member (public or private)
Has push permissions to the repository

Listed in the OWNERS file in the default branch:

OWNERS

approvers:
  - alice
  - bob
reviewers:
  - charlie
  - diana

Both approvers and reviewers can trigger PipelineRuns.

Use aliases for teams:

OWNERS_ALIASES

aliases:
  team-leads:
    - alice
    - bob
  contributors:
    - charlie
    - diana

OWNERS

approvers:
  - team-leads
reviewers:
  - contributors

Explicitly allow users in the Repository CR:

spec:
  settings:
    policy:
      pull_request:
        - external-contributor
      ok_to_test:
        - maintainer1
        - maintainer2

Unauthorized Users

When an unauthorized user opens a PR, PAC:

Posts a Pending status check
Comments that the user lacks permissions
Waits for an authorized user to comment /ok-to-test

GitHub bot users (detected via the GitHub API) are silently ignored unless explicitly authorized.

`/ok-to-test` Command

Authorized users can approve external PRs:

Looks good! Thanks for the contribution.

/ok-to-test

SHA Validation (GitHub only)

Cluster administrators can require SHA validation for /ok-to-test:

apiVersion: v1
kind: ConfigMap
metadata:
  name: pipelines-as-code
  namespace: pipelines-as-code
data:
  require-ok-to-test-sha: "true"

Users must then include the commit SHA:

/ok-to-test 1a2b3c4

This prevents time-of-check/time-of-use attacks where an attacker pushes new code immediately after approval.

Draft Pull Requests (GitHub)

By default, PAC runs on draft PRs. To skip drafts:

annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" && !body.pull_request.draft

PipelineRuns trigger only when the PR is marked “Ready for Review.”

Monitoring Execution

Using tkn pac CLI

View logs for the latest PipelineRun:

tkn pac logs -n my-namespace -L

Select a specific PipelineRun:

tkn pac logs -n my-namespace

You’ll be prompted to choose from recent runs.

Using Tekton Dashboard

If the Tekton Dashboard is installed, PAC posts a direct link in the GitHub Checks tab.

Using OpenShift Console

On OpenShift, PAC links to the Pipeline view in the Console.

Git Provider UI

GitHub
GitLab
Forgejo/Gitea

Check the Checks tab on pull requests: GitHub Checks

Each PipelineRun appears as a separate check with:

Status (pending, success, failure)
Task-by-task results
Log snippets
Execution time

Error Handling

YAML Parsing Errors

If PAC encounters invalid YAML in .tekton/:

Comment on PR: Details the error
Namespace Events: Error logged in namespace event stream
Controller Logs: Error appears in PAC controller logs

Example Error Comment: YAML Error Comment

YAML syntax errors halt execution of all PipelineRuns, even valid ones. Validation errors only affect the invalid PipelineRun.

Check namespace events:

kubectl get events -n my-namespace --sort-by='.lastTimestamp'

Subsequent PR Updates

Error comments are updated on new commits:

New errors replace the comment
Fixed errors leave the comment (not deleted)

Cancelling PipelineRuns

Cancel In-Progress (Automatic)

Automatically cancel older runs when new commits are pushed:

metadata:
  annotations:
    pipelinesascode.tekton.dev/cancel-in-progress: "true"

Behavior:

Only cancels runs for the same PR or same branch (push events)
Different PRs are isolated from each other
Cancellation happens after the new PipelineRun starts
Not compatible with concurrency_limit

Closed PR Cancellation: If a PR is closed/declined, all in-progress PipelineRuns are cancelled.

Cancel via GitOps Command

Cancel all PipelineRuns on a PR:

/cancel

Cancel a specific PipelineRun:

/cancel my-pipeline-name

See GitOps Commands for more details.

Restarting PipelineRuns

GitHub Apps: Re-Run Button

Click Re-Run in the Checks tab: GitHub Re-Run

You can:

Re-run a single pipeline
Re-run all checks

GitOps Commands

Restart failed PipelineRuns:

/retest

Restart a specific PipelineRun:

/retest my-pipeline-name

Force restart (even if succeeded):

/test my-pipeline-name

See GitOps Commands for complete details.

Skip CI

Skip automatic pipeline execution by including skip commands in commit messages:

docs: update README [skip ci]

Supported skip commands (case-sensitive):

[skip ci]
[ci skip]
[skip tkn]
[tkn skip]

How It Works

Pull Requests
Push Events

No PipelineRuns created when PR opened/updated
Neutral status check posted (“CI skipped”)
Can still trigger manually with GitOps commands

GitOps Override

Skip commands can be overridden:

# Commit with skip command
git commit -m "docs: update guide [skip ci]"
git push
# No pipelines run automatically

# Later, manually trigger via PR comment:
# /test

When to Use Skip Commands

Good Use Cases
Avoid For

Documentation-only changes
README updates
Comment/formatting changes
WIP commits
Minor typo fixes

Execution Namespace

PipelineRuns always execute in the namespace of the Repository CR.

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: my-repo
  namespace: my-namespace  # PipelineRuns run here
spec:
  url: "https://github.com/owner/repo"

For security, explicitly target the namespace in PipelineRuns:

annotations:
  pipelinesascode.tekton.dev/target-namespace: "my-namespace"

Status Updates

GitHub

GitHub Apps:

Detailed Checks with task-by-task status
Log snippets on failures
Task execution time
Secrets automatically redacted

GitHub Webhooks:

Commit status (pending, success, failure)
Link to logs

GitLab

Commit status updates:

Try source project (fork)
Fallback to target project
Comment if both fail

Forgejo/Gitea

Commit status on pull requests with overall pass/fail.

Best Practices

Use OWNERS files

Define authorized users in version control:

approvers:
  - team-lead
  - senior-dev
reviewers:
  - developer1
  - developer2

Configure comment strategy

Reduce notification noise:

spec:
  settings:
    github:
      comment_strategy: "update"  # Single comment, updated on each run

Set concurrency limits

Prevent resource exhaustion:

spec:
  concurrency_limit: 3

Enable auto-cancellation

Save resources on rapid commits:

annotations:
  pipelinesascode.tekton.dev/cancel-in-progress: "true"

Use default branch provenance

Enforce pipeline review process:

spec:
  settings:
    pipelinerun_provenance: "default_branch"

Troubleshooting

PipelineRuns not triggering

Check authorization

Verify the user is authorized:

# Check OWNERS file
curl https://raw.githubusercontent.com/owner/repo/main/OWNERS

Verify Repository CR

kubectl get repository -n my-namespace
kubectl describe repository my-repo -n my-namespace

Check event matching

Ensure annotations match the event:

annotations:
  pipelinesascode.tekton.dev/on-event: "[pull_request]"  # Must match event type
  pipelinesascode.tekton.dev/on-target-branch: "[main]"  # Must match target branch

Review PAC controller logs

kubectl logs -n pipelines-as-code -l app.kubernetes.io/name=controller

GitHub bot issues

If GitHub bots aren’t triggering:

Bots are silently ignored unless authorized
Add bots to OWNERS or Repository CR policy:

spec:
  settings:
    policy:
      pull_request:
        - "dependabot[bot]"
        - "renovate[bot]"

Draft PR not skipping

Add CEL expression:

annotations:
  pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" && !body.pull_request.draft

Next Steps

GitOps Commands

Control pipelines with /test, /retest, and /cancel commands

Event Matching

Advanced event matching with CEL expressions

Pipeline Resolution

Remote task and pipeline resolution

Repository CRD

Configure authorization policies

Getting Started

Installation

Git Provider Setup

Core Guides

Advanced Features

Operations

​Overview

​How Execution Works

​ACL Permissions

​Unauthorized Users

​/ok-to-test Command

​SHA Validation (GitHub only)

​Draft Pull Requests (GitHub)

​Monitoring Execution

​Using tkn pac CLI

​Using Tekton Dashboard

​Using OpenShift Console

​Git Provider UI

​Error Handling

​YAML Parsing Errors

​Subsequent PR Updates

​Cancelling PipelineRuns

​Cancel In-Progress (Automatic)

​Cancel via GitOps Command

​Restarting PipelineRuns

​GitHub Apps: Re-Run Button

​GitOps Commands

​Skip CI

​How It Works

​GitOps Override

​When to Use Skip Commands

​Execution Namespace

​Status Updates

​GitHub

​GitLab

​Forgejo/Gitea

​Best Practices

​Troubleshooting

​PipelineRuns not triggering

​GitHub bot issues

​Draft PR not skipping

​Next Steps

GitOps Commands

Event Matching

Pipeline Resolution

Repository CRD

Build docs developers (and LLMs) love

Overview

How Execution Works

ACL Permissions

Unauthorized Users

`/ok-to-test` Command

SHA Validation (GitHub only)

Draft Pull Requests (GitHub)

Monitoring Execution

Using tkn pac CLI

Using Tekton Dashboard

Using OpenShift Console

Git Provider UI

Error Handling

YAML Parsing Errors

Subsequent PR Updates

Cancelling PipelineRuns

Cancel In-Progress (Automatic)

Cancel via GitOps Command

Restarting PipelineRuns

GitHub Apps: Re-Run Button

GitOps Commands

Skip CI

How It Works

GitOps Override

When to Use Skip Commands

Execution Namespace

Status Updates

GitHub

GitLab

Forgejo/Gitea

Best Practices

Troubleshooting

PipelineRuns not triggering

GitHub bot issues

Draft PR not skipping

Next Steps