Managing pipeline runs

The Pipelines as Code resolver bundles the pipeline runs with all tasks as a single pipeline run without external dependencies.

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 match different Git provider events with each pipeline run by using special annotations on the pipeline run. If there are multiple pipeline runs matching an event, Pipelines as Code runs them in parallel and posts the results to the Git provider as soon a pipeline run finishes.

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

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:

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:

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:

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

For example, to add a comment to a pull request, you can use the github-add-comment task from Tekton Hub using a Pipelines as Code annotation:

You can then add a task to the tasks section or finally tasks in the pipeline run definition:

In the event of a pull request or a merge request, Pipelines as Code also runs pipelines from branches other than the default branch, if the following conditions are met by the author of the pull request:

If the pull request author does not meet the requirements, another user who meets the requirements can comment /ok-to-test on the pull request, and start the pipeline run.

A pipeline run always runs in the namespace of the Repository custom resource definition (CRD) associated with the repository that generated the event.

You can observe the execution of your pipeline runs using the tkn pac CLI tool.

If you have configured Pipelines as Code with a GitHub App, Pipelines as Code posts a URL in the Checks tab of the GitHub App. You can click the URL and follow the pipeline execution.

You can restart or cancel a pipeline run with no events, such as sending a new commit to your branch or raising a pull request. To restart all pipeline runs, use the Re-run all checks feature in the GitHub App.

To restart all or specific pipeline runs, use the following comments:

To cancel all or specific pipeline runs, use the following comments:

The results of the comments are visible under the Checks tab of the GitHub App.

The comment starts, restarts, or cancels any pipeline runs only if the comment author meets one of the following requirements:

When a pipeline run finishes, the status is added in the Check tabs with limited information on how long each task of your pipeline took, and the output of the tkn pipelinerun describe command.

When Pipelines as Code detects an error in one of the tasks of a pipeline, a small snippet consisting of the last 3 lines in the task breakdown of the first failed task is displayed.

In the TektonConfig custom resource, in the pipelinesAsCode.settings spec, you can set the error-detection-from-container-logs parameter to true. In this case, Pipelines as Code detects the errors from the container logs and adds them as annotations on the pull request where the error occurred.

Currently, Pipelines as Code supports only the simple cases where the error looks like makefile or grep output of the following format:

You can customize the regular expression used to detect the errors with the error-detection-simple-regexp parameter. The regular expression uses named groups to give flexibility on how to specify the matching. The groups needed to match are filename, line, and error. You can view the Pipelines as Code config map for the default regular expression.

For webhook, when the event is a pull request, the status is added as a comment on the pull or merge request.

If a namespace is matched to a Repository custom resource definition (CRD), Pipelines as Code emits its failure log messages in the Kubernetes events inside the namespace.

The last 5 status messages for a pipeline run is stored inside the Repository custom resource.

Using the tkn pac describe command, you can extract the status of the runs associated with your repository and its metadata.

Pipelines as Code does not manage notifications. If you need to have notifications, use the finally feature of pipelines.

To use incoming webhooks, specify the following within the spec section of the Repository custom resource definition (CRD):

To trigger a pipeline run located in the .tekton directory of a Git repository, use the following command:

Pipelines as Code matches the incoming URL and treats it as a push event. However, Pipelines as Code does not report status of the pipeline runs triggered by this command.

To get a report or a notification, add it directly with a finally task to your pipeline. Alternatively, you can inspect the Repository CRD with the tkn pac CLI tool.