Creating Pipeline Definitions

Overview

Pipelines-as-Code allows you to define your Tekton pipelines directly in your Git repository. Pipeline definitions are stored in the .tekton/ directory and automatically executed when Git events occur.

Pipelines-as-Code stays as close to standard Tekton templates as possible. Write your templates as .yaml files, and PAC will run them.

Directory Structure

The .tekton directory must be at the top level of your repository:

your-repo/
├── .tekton/
│   ├── pull-request.yaml
│   ├── push-main.yaml
│   └── tasks/
│       └── custom-task.yaml
├── src/
└── README.md

Create the .tekton directory

Create a .tekton directory at the root of your repository:

mkdir .tekton

Generate a basic PipelineRun

Use the tkn pac CLI to generate a template:

tkn pac generate

You’ll be prompted for:

Git event type: Pull Request or Push

Target branch: e.g., main

This creates a basic template in .tekton/pull-request.yaml.

Customize your PipelineRun

Edit the generated file to add your build/test logic:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pr-build
  annotations:
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
spec:
  params:
    - name: repo_url
      value: "{{ repo_url }}"
    - name: revision
      value: "{{ revision }}"
  pipelineSpec:
    params:
      - name: repo_url
      - name: revision
    tasks:
      - name: fetch-repository
        taskRef:
          name: git-clone
          resolver: hub
        workspaces:
          - name: output
            workspace: source
        params:
          - name: url
            value: "$(params.repo_url)"
          - name: revision
            value: "$(params.revision)"
      - name: run-tests
        runAfter: [fetch-repository]
        taskRef:
          name: golang-test
          resolver: hub
        workspaces:
          - name: source
            workspace: source
  workspaces:
    - name: source
      emptyDir: {}

Dynamic Variables

Pipelines-as-Code provides template variables that are replaced at runtime with values from the Git event.

Essential Variables

repo_url

string

The full URL of the repositoryExample: https://github.com/openshift-pipelines/pipelines-as-code

revision

string

The commit SHA being testedExample: 1234567890abcdef

target_branch

string

The branch the event targets (for PRs: base branch; for push: the branch pushed to)Example: main

source_branch

string

The branch where the event originates (for PRs: head branch; for push: same as target_branch)Example: feature/my-feature

All Available Variables

Variable	Description	Example
`body`	Full webhook payload	`{{ body.pull_request.user.email }}`
`event`	Normalized event type	`pull_request`, `push`, or `incoming`
`event_type`	Provider-specific event type	`pull_request` (GitHub), `Merge Request` (GitLab)
`git_auth_secret`	Auto-generated secret for private repos	`pac-gitauth-xkxkx`
`headers`	Request headers	`{{ headers['x-github-event'] }}`
`pull_request_number`	PR/MR number	`42`
`repo_name`	Repository name	`pipelines-as-code`
`repo_owner`	Repository owner	`openshift-pipelines`
`repo_url`	Full repository URL	`https://github.com/openshift-pipelines/pipelines-as-code`
`revision`	Commit SHA	`1234567890abcdef`
`sender`	Username of the event sender	`johndoe`
`source_branch`	Source branch name	`feature-branch`
`git_tag`	Git tag (only for tag push events)	`v1.0.0`
`source_url`	Source repository URL	`https://github.com/fork/repo`
`target_branch`	Target branch name	`main`
`target_namespace`	Namespace where Repository CR matched	`my-namespace`
`trigger_comment`	Comment that triggered the run (GitOps commands)	`/test my-pipeline`
`pull_request_labels`	PR labels (newline-separated)	`bug\nenhancement`

Using Variables

Variables use double-brace syntax: {{ variable_name }}

params:
  - name: git-url
    value: "{{ repo_url }}"
  - name: git-revision
    value: "{{ revision }}"

Advanced Variable Usage

Accessing Webhook Body

You can access any field from the webhook payload:

params:
  - name: pr-title
    value: "{{ body.pull_request.title }}"
  - name: author-email
    value: "{{ body.pull_request.user.email }}"

Object Values in YAML

When passing objects or multiline values, use block format:

params:
  - name: body
    value: |-
      {{ body }}
  - name: pull_request
    value: >
      {{ body.pull_request }}

CEL Expressions

For complex expressions, use the cel: prefix:

params:
  - name: environment
    value: "{{ cel: pac.target_branch == 'main' ? 'production' : 'staging' }}"
  - name: commit-type
    value: "{{ cel: has(body.head_commit) && body.head_commit.message.startsWith('Merge') ? 'merge' : 'regular' }}"
  - name: go-files-changed
    value: "{{ cel: files.all.exists(f, f.endsWith('.go')) ? 'true' : 'false' }}"

CEL expressions have access to:

body - Full webhook payload
headers - HTTP headers
files - Changed files (files.all, files.added, files.deleted, files.modified, files.renamed)
pac - Standard PAC parameters (pac.revision, pac.target_branch, etc.)

PipelineRun Structure

Required Components

Unique Name

Each PipelineRun must have a unique name:

metadata:
  name: unique-pipeline-name  # Must be unique across all PipelineRuns

PipelineRuns with duplicate names will never be matched.

Event Matching Annotations

At minimum, specify which events trigger the pipeline:

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

PipelineSpec or PipelineRef

Define your pipeline inline or reference an external one:

Inline PipelineSpec

spec:
  pipelineSpec:
    tasks:
      - name: build
        taskSpec:
          steps:
            - name: build-step
              image: golang:1.21
              script: |
                go build ./...

PipelineRef

spec:
  pipelineRef:
    name: my-pipeline
  # Pipeline definition in .tekton/pipeline.yaml

Complete Examples

Python CI Pipeline

.tekton/python-ci.yaml

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: python-ci
  annotations:
    pipelinesascode.tekton.dev/on-event: "[pull_request, push]"
    pipelinesascode.tekton.dev/on-target-branch: "[main, develop]"
spec:
  pipelineSpec:
    tasks:
      - name: fetch-source
        taskRef:
          name: git-clone
          resolver: hub
        workspaces:
          - name: output
            workspace: source
        params:
          - name: url
            value: "{{ repo_url }}"
          - name: revision
            value: "{{ revision }}"
      - name: python-test
        runAfter: [fetch-source]
        taskRef:
          name: python-test
          resolver: hub
        workspaces:
          - name: source
            workspace: source
        params:
          - name: requirements_file
            value: "requirements.txt"
          - name: python_version
            value: "3.11"
  workspaces:
    - name: source
      emptyDir: {}

Container Build Pipeline

.tekton/build-push.yaml

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: build-push
  annotations:
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
spec:
  pipelineSpec:
    tasks:
      - name: fetch-source
        taskRef:
          name: git-clone
          resolver: hub
        workspaces:
          - name: output
            workspace: source
        params:
          - name: url
            value: "{{ repo_url }}"
          - name: revision
            value: "{{ revision }}"
      - name: build-push
        runAfter: [fetch-source]
        taskRef:
          name: buildah
          resolver: hub
        workspaces:
          - name: source
            workspace: source
        params:
          - name: IMAGE
            value: "quay.io/myorg/myapp:{{ revision }}"
          - name: DOCKERFILE
            value: "./Dockerfile"
  workspaces:
    - name: source
      emptyDir: {}

Conditional Execution

.tekton/docs-validation.yaml

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: docs-validation
  annotations:
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-path-change: "[docs/**, **.md]"
spec:
  pipelineSpec:
    tasks:
      - name: fetch-source
        taskRef:
          name: git-clone
          resolver: hub
        workspaces:
          - name: output
            workspace: source
        params:
          - name: url
            value: "{{ repo_url }}"
          - name: revision
            value: "{{ revision }}"
      - name: lint-docs
        runAfter: [fetch-source]
        taskRef:
          name: markdown-lint
          resolver: hub
        workspaces:
          - name: source
            workspace: source
  workspaces:
    - name: source
      emptyDir: {}

Using GitHub App Token

Access the GitHub API using the temporary installation token:

tasks:
  - name: add-comment
    taskRef:
      name: github-add-comment
    params:
      - name: REQUEST_URL
        value: "{{ repo_url }}/pull/{{ pull_request_number }}"
      - name: COMMENT_OR_FILE
        value: "Build completed successfully!"
      - name: GITHUB_TOKEN_SECRET_NAME
        value: "{{ git_auth_secret }}"
      - name: GITHUB_TOKEN_SECRET_KEY
        value: "git-provider-token"

Or as an environment variable:

env:
  - name: GITHUB_TOKEN
    valueFrom:
      secretKeyRef:
        name: "{{ git_auth_secret }}"
        key: "git-provider-token"

GitHub App tokens are available for 8 hours
Tokens are scoped to the repository by default (configurable via settings)

Best Practices

Always use dynamic variables

Never hardcode repository URLs or commit SHAs:

# ✅ Good
params:
  - name: url
    value: "{{ repo_url }}"

# ❌ Bad
params:
  - name: url
    value: "https://github.com/myorg/myrepo"

Check out code first

Most pipelines start by cloning the repository:

tasks:
  - name: fetch-repository
    taskRef:
      name: git-clone
      resolver: hub
    params:
      - name: url
        value: "{{ repo_url }}"
      - name: revision
        value: "{{ revision }}"

Use unique PipelineRun names

Ensure each PipelineRun has a distinct name to avoid conflicts.

Leverage workspaces

Share data between tasks using workspaces:

workspaces:
  - name: source
    emptyDir: {}

Test locally

Use tkn pac resolve to test your PipelineRun before pushing:

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

Next Steps

Event Matching

Learn how to match PipelineRuns to specific events, branches, and file changes

Pipeline Resolution

Understand how PAC resolves tasks and pipelines from remote sources

Running Pipelines

Configure execution, permissions, and monitoring

Repository CRD

Configure the Repository Custom Resource

Getting Started

Installation

Git Provider Setup

Core Guides

Advanced Features

Operations

Overview

Directory Structure

Dynamic Variables

Essential Variables

All Available Variables

Using Variables

Advanced Variable Usage

Accessing Webhook Body

Object Values in YAML

CEL Expressions

PipelineRun Structure

Required Components

Complete Examples

Python CI Pipeline

Container Build Pipeline

Conditional Execution

Using GitHub App Token

Best Practices

Next Steps

Event Matching

Pipeline Resolution

Running Pipelines

Repository CRD

Build docs developers (and LLMs) love

Getting Started

Installation

Git Provider Setup

Core Guides

Advanced Features

Operations

​Overview

​Directory Structure

​Dynamic Variables

​Essential Variables

​All Available Variables

​Using Variables

​Advanced Variable Usage

​Accessing Webhook Body

​Object Values in YAML

​CEL Expressions

​PipelineRun Structure

​Required Components

​Complete Examples

​Python CI Pipeline

​Container Build Pipeline

​Conditional Execution

​Using GitHub App Token

​Best Practices

​Next Steps

Event Matching

Pipeline Resolution

Running Pipelines

Repository CRD

Build docs developers (and LLMs) love

Overview

Directory Structure

Dynamic Variables

Essential Variables

All Available Variables

Using Variables

Advanced Variable Usage

Accessing Webhook Body

Object Values in YAML

CEL Expressions

PipelineRun Structure

Required Components

Complete Examples

Python CI Pipeline

Container Build Pipeline

Conditional Execution

Using GitHub App Token

Best Practices

Next Steps