Authoring PipelineRun

This page covers how to write PipelineRun definitions that Pipelines-as-Code picks up from your .tekton/ directory. Use it when you need to define CI/CD pipelines triggered by Git events.

Pipelines-as-Code follows the standard Tekton template format as closely as possible. You write your templates as .yaml files in the .tekton/ directory at the top level of your repository, and Pipelines-as-Code runs them. You can reference YAML files in other repositories using remote HTTP URLs, but PipelineRuns only trigger from events in the repository that contains the .tekton/ directory.

Using its resolver, Pipelines-as-Code bundles each PipelineRun with all its referenced Tasks into a single self-contained PipelineRun with no external dependencies.

To check out the commit that triggered the webhook, clone the repository at that ref inside your pipeline. In most cases, you can reuse the git-clone task from the tektoncd/catalog.

To inject parameters such as the commit SHA and repository URL, Pipelines-as-Code provides dynamic variables written as {{ var }} that you can use anywhere in your template.

For Pipelines-as-Code to process your PipelineRun, include either an embedded PipelineSpec or a separate Pipeline object that references a YAML file in the .tekton/ directory. The Pipeline object can include TaskSpecs, which you may define separately as Tasks in another YAML file in the same directory. Give each PipelineRun a unique name to avoid conflicts.

Dynamic variables

Dynamic variables are placeholder tokens written as {{ variable_name }} that Pipelines-as-Code replaces with real values at runtime. They let you write generic PipelineRun templates that automatically adapt to each event without hardcoding repository URLs, branch names, or commit SHAs.

The following table lists all available dynamic variables. The most commonly used are revision and repo_url, which provide the commit SHA and repository URL being tested. Use these with the git-clone task to check out the code under test.

Defining parameters with object values in YAML

When you define parameters in YAML, you may need to pass an object or a dynamic variable (for example, {{ body }}) as a parameter value. YAML validation rules prevent such values from appearing inline.

For instance, if you attempt to define a parameter like this:

spec:
  params:
    - name: body
      value: {{ body }}  # This will result in a YAML validation error
  pipelineSpec:
    tasks:

This produces a YAML validation error because objects or multiline strings cannot appear inline. To fix this, define the value in block format instead:

spec:
  params:
    - name: body
      value: |-
        {{ body }}
    # Alternatively, use '>' to specify that the value will be in block format
    - name: pull_request
      value: >
        {{ body.pull_request }}
  pipelineSpec:
    tasks:

Using block format avoids validation errors and keeps your YAML properly structured.

Matching an event to a PipelineRun

Each PipelineRun can match different Git provider events through special annotations on the PipelineRun. This is how you control which pipelines run for which branches and event types.

For example, with the following metadata on your PipelineRun:

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

Pipelines-as-Code matches the PipelineRun pipeline-pr-main if the Git provider event targets the branch main and originates from a pull_request.

There are many ways to match an event to a PipelineRun. See the event matching page for details on all available matching options.

Example

Pipelines-as-Code tests itself using this approach. You can see working examples in its .tekton directory.