Chapter 6. Managing pipeline runs

You can specify the parameters of your commit and URL by using dynamic, expandable variables with the {{<var>}} format. Currently, you can use the following variables:

You can use the temporary installation token generated by Pipelines as Code from the GitHub App to access the GitHub API. The GitHub App generates a key for private repositories in the git-provider-token key. You can use the {{git_auth_secret}} dynamic variable in pipeline runs to access this key.

For example, if your pipeline run must add a comment to a pull request, you can use the a Pipelines as Code annotation to fetch the github-add-comment task definition from Tekton Hub, and then define the task that adds the comment, as shown in the following example:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-with-comment
annotations:
  pipelinesascode.tekton.dev/task: "github-add-comment"
spec:
  pipelineSpec:
    tasks:
      - name: add-sample-comment
        taskRef:
          name: github-add-comment
        params:
          - name: REQUEST_URL
            value: "{{ repo_url }}/pull/{{ pull_request_number }}" 1
          - name: COMMENT_OR_FILE
            value: "Pipelines as Code IS GREAT!"
          - name: GITHUB_TOKEN_SECRET_NAME
            value: "{{ git_auth_secret }}"
          - name: GITHUB_TOKEN_SECRET_KEY
            value: "git-provider-token"

You can use the following example to match the pipeline-pr-main pipeline run with a pull_request event that targets the main branch:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-pr-main
annotations:
  pipelinesascode.tekton.dev/on-target-branch: "[main]" 1
  pipelinesascode.tekton.dev/on-event: "[pull_request]"
# ...

You can use the following example to match the pipeline-push-on-main pipeline run with a push event targeting the refs/heads/main branch:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-push-on-main
annotations:
  pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" 1
  pipelinesascode.tekton.dev/on-event: "[push]"
# ...

You can match a pipeline run to changes in a set of paths. Pipelines as Code starts the pipeline run when a pull request includes changes in any of the paths that you list.

The * wildcard denotes any file in the directory. The ** wildcard denotes any file in the directory or any subdirectories on any level under the directory.

You can use the following example to match the pipeline-pkg-or-cli pipeline run when a pull request changes any files in the pkg directory, the cli directory, or any subdirectories under the cli directory.

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-pkg-or-cli
annotations:
  pipelinesascode.tekton.dev/on-path-changed: "["pkg/*", "cli/**"]"
# ...

You can configure a pipeline run to exclude matching if a pull request makes changes only to files in a specified set of paths. If the pipeline run matches an event but the pull request includes changes only to files in the paths that you list, Pipelines as Code does not start the pipeline run.

You can use the following example to match the pipeline-docs-not-generated pipeline run when a pull request changes any files under the docs directory or its subdirectories, except when the changes apply only to the docs/generated directory or its subdirectories.

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-docs-not-generated
annotations:
  pipelinesascode.tekton.dev/on-path-changed: "["docs/**"]"
  pipelinesascode.tekton.dev/on-path-changed-ignore: "["docs/generated/**"]"
# ...

You can use the following example to match the pipeline-main-not-docs pipeline run when a pull request targets the main branch, except when the changes apply only to the docs directory or its subdirectories.

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-main-not-docs
annotations:
  pipelinesascode.tekton.dev/on-target-branch: "[main]"
  pipelinesascode.tekton.dev/on-event: "[pull_request]"
  pipelinesascode.tekton.dev/on-path-changed-ignore: "["docs/**"]"
# ...

You can match a pipeline run to one or several pull request labels. Pipelines as Code starts the pipeline run when any of these labels is added to a pull request. When the pull request is updated with a new commit, if the pull request still has the label, Pipelines as Code starts the pipeline run again.

You can use the following example to match the pipeline-bug-or-defect pipeline run when either the bug label or the defect label is added to a pull request, and also when a pull request with this label is updated with a new commit:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-bug-or-defect
annotations:
  pipelinesascode.tekton.dev/on-label: "[bug, defect]"
# ...

You can use the following example to match the pipeline-comment pipeline run with a comment on a pull request, when the text of the comment matches the ^/merge-pr regular expression:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-comment
annotations:
  pipelinesascode.tekton.dev/on-comment: "^/merge-pr"
# ...

The pipeline run starts only if the comment author meets one of the following requirements:

Pipelines as Code supports using Common Expression Language (CEL) based filtering for advanced event matching. If you have the pipelinesascode.tekton.dev/on-cel-expression annotation in your pipeline run, Pipelines as Code uses the CEL expression and skips the on-target-branch annotation. Compared to the simple on-target-branch annotation matching, the CEL expressions allow complex filtering and negation.

To use CEL-based filtering with Pipelines as Code, consider the following examples of annotations:

For advanced CEL-based filtering while using Pipelines as Code, you can use the following fields and suffix functions:

In addition, you can access the full payload as passed by the Git repository provider. Use the headers field to access the headers of the payload, for example, headers['x-github-event']. Use the body field to access the body of the payload, for example, body.pull_request.state.

In the following example, the pipeline run starts only if all of the following conditions are true:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  annotations:
    pipelinesascode.tekton.dev/on-cel-expression: |
      body.pull_request.base.ref == "main" &&
        body.pull_request.user.login == "superuser" &&
        body.action == "synchronize"
# ...

git commit --amend --no-edit && git push --force-with-lease