Skip to main content
This page provides detailed flow diagrams to help you understand how events are processed through Pipelines as Code.

​
Pull/Merge Request Flow

This diagram shows the complete flow when a pull request or merge request is opened: PAC Diagram

​
Flow Steps

1

User Action

A developer opens a pull request, pushes a commit, or creates a tag in their Git repository.
2

Webhook Event

The Git provider (GitHub, GitLab, Bitbucket, or Forgejo) sends a webhook HTTP POST request to the PAC webhook endpoint.
3

Event Reception

The webhook handler receives the event and validates:
  • Webhook signature authentication
  • Event payload format
  • Skip CI markers ([skip ci], [ci skip])
4

Repository Lookup

The controller:
  • Finds the matching Repository CRD in Kubernetes
  • Retrieves authentication credentials from secrets
  • Validates repository configuration
5

Permission Validation

The ACL system checks:
  • User is authorized (org member, collaborator, in OWNERS file)
  • Event doesn’t require /ok-to-test approval
  • Repository policy allows execution
6

Pipeline Discovery

The resolver:
  • Fetches the .tekton/ directory from the repository
  • Parses all YAML files for PipelineRun definitions
  • Filters pipelines based on event type and annotations
7

Pipeline Matching

For each pipeline, check:
  • on-event annotation matches event type
  • on-target-branch matches target branch
  • on-cel-expression evaluates to true (if present)
  • on-path-change matches changed files (if present)
8

Task Resolution

Resolve remote tasks from:
  • Tekton Hub (resolver: hub)
  • Artifact Hub
  • OCI bundles (resolver: bundles)
  • Git repositories (resolver: git)
9

Variable Substitution

Substitute template variables:
  • {{repo_url}} → Git repository clone URL
  • {{revision}} → Git commit SHA
  • {{target_branch}} → Pull request target branch
  • {{source_branch}} → Pull request source branch
  • Custom variables from ConfigMap
10

PipelineRun Creation

Create PipelineRun on Kubernetes with:
  • Resolved pipeline specification
  • Workspaces and volume claims
  • Secrets and service accounts
  • Labels and annotations for tracking
11

Execution Monitoring

The watcher monitors the PipelineRun:
  • Watches for status changes
  • Reports progress to Git provider
  • Creates GitHub Checks, GitLab notes, etc.
12

Status Reporting

As the pipeline executes, report:
  • In-progress status with task details
  • Task completion and timing
  • Log snippets for failures
  • Error annotations (GitHub only)
13

Completion

When the pipeline completes:
  • Report final status (success/failure)
  • Post summary comment with logs
  • Update Repository CRD status
  • Schedule cleanup if retention policy configured

​
Concurrency Flow

This diagram shows how PAC manages concurrent pipeline executions:

​
Concurrency States

When: Concurrency limit reachedBehavior:
  • PipelineRun created with .status.conditions[].reason=Pending
  • Added to FIFO queue for the repository
  • State annotation: pipelinesascode.tekton.dev/state=queued
Duration: Until a running PipelineRun completes

​
Concurrency Configuration

Set concurrency limit with annotation: 
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  annotations:
    pipelinesascode.tekton.dev/max-concurrency: "1"
Use Cases:
  • Prevent multiple deployments to the same environment
  • Limit resource consumption
  • Ensure sequential execution for stateful operations
  • Avoid race conditions in integration tests

​
GitOps Command Flow

This diagram shows how GitOps commands (/test, /retest, /cancel) are processed:

​
Supported Commands

Purpose: Trigger a specific pipeline or all matched pipelinesUsage:
/test                    # Run all matched pipelines
/test build              # Run pipeline named "build"
/test integration-tests  # Run pipeline named "integration-tests"
Requirements:
  • User must have write access to the repository
  • Pipeline must match current event and branch
Purpose: Re-run all previously failed pipelinesUsage:
/retest  # Re-run all failed pipelines
Behavior:
  • Only re-runs pipelines that failed
  • Successful pipelines are not re-run
  • Uses current .tekton/ files (not from failed run)
Purpose: Cancel all running pipelines for the PRUsage:
/cancel  # Cancel all running pipelines
Behavior:
  • Deletes all running PipelineRuns
  • Does not affect completed pipelines
  • Reports cancellation status to Git provider
Purpose: Approve pipelines for untrusted PRs (from forks)Usage:
/ok-to-test  # Approve and run pipelines
Requirements:
  • Only available when policy requires approval
  • User must be repository admin or in OWNERS file
  • Approval is one-time (new commits require re-approval)

​
Auto-Cancellation Flow

When a new commit is pushed to a branch with running pipelines:

​
Configuration

Enable auto-cancellation with annotation: 
metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cancel: "running"
Values:
  • running: Cancel only running pipelines on new commits
  • pending: Cancel pending (queued) pipelines only
  • all: Cancel both running and pending pipelines

​
Cleanup Flow

PAC automatically cleans up old PipelineRuns:

​
Configuration

Global Setting (ConfigMap): 
apiVersion: v1
kind: ConfigMap
metadata:
  name: pipelines-as-code
data:
  max-keep-runs: "10"
Per-Repository (Repository CRD): 
apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  annotations:
    pipelinesascode.tekton.dev/max-keep-runs: "5"

​
Event Types and Triggers

Different events trigger different flows:
Triggered On:
  • Pull request opened
  • New commits pushed to PR
  • PR synchronized
Event Type: pull_requestAnnotations:
pipelinesascode.tekton.dev/on-event: "[pull_request]"
pipelinesascode.tekton.dev/on-target-branch: "[main]"
Variables Available:
  • {{source_branch}}: PR source branch
  • {{target_branch}}: PR target branch
  • {{pull_request_number}}: PR number

​
Error Handling Flow

How PAC handles errors at different stages:

​
Error Responses

PAC provides detailed error feedback:
  • Webhook validation failure: HTTP 401/403 response
  • Repository not found: GitHub issue comment explaining setup
  • Permission denied: Comment requesting /ok-to-test
  • YAML syntax error: Comment with line number and error
  • Task resolution failure: Comment with task name and resolver
  • PipelineRun creation failure: Comment with Kubernetes error

​
Next Steps

Architecture

Understand the PAC architecture

Testing Guide

Learn how to test event flows

Development Setup

Set up your development environment

Contributing

Start contributing to PAC

Build docs developers (and LLMs) love

Get started for freeTalk to us