Authoring PipelineRuns in .tekton/ directory #

• Pipelines-as-Code will always try to be as close to the Tekton template as possible. Usually, you will write your template and save them with a .yaml extension, and Pipelines-as-Code will run them.

• The .tekton directory must be at the top level of the repo. You can reference YAML files in other repos using remote URLs (see Remote HTTP URLs for more information), but PipelineRuns will only be triggered by events in the repository containing the .tekton directory.

• Using its resolver Pipelines-as-Code will try to bundle the PipelineRun with all its Tasks as a single PipelineRun with no external dependencies.

• Inside your pipeline, you need to be able to check out the commit as received from the webhook by checking out the repository from that ref. Most of the time you want to reuse the git-clone task from the tektoncd/catalog.

• To be able to specify parameters of your commit and URL, Pipelines-as-Code gives you some “dynamic” variables that are defined according to the execution of the events. Those variables look like this {{ var }} and can be used anywhere in your template, see below for the list of available variables.

• For Pipelines-as-Code to process your PipelineRun, you must have 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 may be defined separately as Tasks in another YAML file in the same directory. It’s important to give each PipelineRun a unique name to avoid conflicts. PipelineRuns with duplicate names will never be matched.

Dynamic variables #

Here is a list of all the dynamic variables available in Pipelines-as-Code. The one that would be the most important to you would probably be the revision and repo_url variables, they will give you the commit SHA and the repository URL that is getting tested. You usually use this with the git-clone task to be able to check out the code that is being tested.

Defining Parameters with Object Values in YAML #

When working with YAML, particularly when defining parameters, you might encounter situations where you need to pass an object or a dynamic variable (e.g., {{ body }}) as the value of a parameter. However, YAML’s validation rules prevent such values from being defined 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:

You will encounter a YAML validation error because objects or multiline strings cannot be placed inline. To resolve this issue and ensure your YAML is correctly validated, you should define the value in block format instead of inline. Here’s an example:

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:

By using the block format, you can avoid validation errors and ensure that your YAML is properly structured.

Matching an event to a PipelineRun #

Each PipelineRun can match different Git provider events through some special annotations on the PipelineRun.

For example, when you have these metadata in 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 will match the PipelineRun pipeline-pr-main if the Git provider events target the branch main and it’s coming from a [pull_request]

There are many ways to match an event to a PipelineRun, head over to this patch page for more details.

Using the body and headers in a Pipelines-as-Code parameter #

Pipelines-as-Code lets you access the full body and headers of the request as a CEL expression.

This allows you to go beyond the standard variables and even play with multiple conditions and variables to output values.

For example, if you want to get the title of the Pull Request in your PipelineRun you can simply access it like this:

{{ body.pull_request.title }}

You can then get creative and for example mix the variable inside a python script to evaluate the json.

This task, for example, is using python and will check the labels on the PR, exit 0 if it has the label called ‘bug’ on the pull request or exit 1 if it doesn’t:

taskSpec:
  steps:
    - name: check-label
      image: registry.access.redhat.com/ubi9/ubi
      script: |
        #!/usr/bin/env python3
        import json
        labels=json.loads("""{{ body.pull_request.labels }}""")
        for label in labels:
            if label['name'] == 'bug':
              print('This is a PR targeting a BUG')
              exit(0)
        print('This is not a PR targeting a BUG :(')
        exit(1)        

The expressions are CEL expressions so you can as well make some conditional:

- name: bash
  image: registry.access.redhat.com/ubi9/ubi
  script: |
    if {{ body.pull_request.state == "open" }}; then
      echo "PR is Open"
    fi    

if the PR is open the condition then returns true and the shell script sees this as a valid boolean.

Headers from the payload body can be accessed from the headers keyword, note that headers are case-sensitive, for example, this will show the GitHub event type for a GitHub event:

{{ headers['X-Github-Event'] }}

and then you can do the same conditional or access as described above for the body keyword.

Using the temporary GitHub APP Token for GitHub API operations #

You can use the temporary installation token that is generated by Pipelines as Code from the GitHub App to access the GitHub API.

The token value is stored in the temporary git-auth secret as generated for private repositories in the key git-provider-token.

As an example, if you want to add a comment to your pull request, you can use the github-add-comment task from the Tekton Hub using a pipelines as code annotation:

pipelinesascode.tekton.dev/task: "github-add-comment"

you can then add the task to your tasks section (or finally tasks) of your PipelineRun :

[...]
tasks:
  - name:
      taskRef:
        name: github-add-comment
      params:
        - name: REQUEST_URL
          value: "{{ repo_url }}/pull/{{ pull_request_number }}"
        - 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"

Since we are using the dynamic variables we are able to reuse this on any PullRequest from any repositories.

and for completeness, here is another example of how to set the GITHUB_TOKEN environment variable on a task step:

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

• On GitHub apps the generated installation token will be available for 8 hours
• On GitHub apps the token is scoped to the repository the event (payload) comes from unless configured differently on the cluster.

Example #

Pipelines as code test itself, you can see the examples in its .tekton repository.