Using Pipelines as Code

Pipelines as Code supports the following features:

To disable the default installation of Pipelines as Code with the Operator, set the value of the enable parameter to false in the TektonConfig custom resource.

Optionally, you can run the following command:

To enable the default installation of Pipelines as Code with the Red Hat OpenShift Pipelines Operator, set the value of the enable parameter to true in the TektonConfig custom resource:

Optionally, you can run the following command:

You can install the tkn pac and opc version 1.9.1 binaries for the supported platforms:

You can use the tkn pac CLI or other alternative methods to create a Repository CR inside the target namespace. For example:

Whenever there is an event coming from the URL such as https://github.com/<repository>/<project>;, Pipelines as Code matches it and starts checking out the content of the <repository>/<project> repository for pipeline run to match the content in the .tekton/ directory.

To split your pipeline and pipeline run, store the files in the .tekton/ directory or its subdirectories.

If Pipelines as Code observes a pipeline run with a reference to a task or a pipeline in any YAML file located in the .tekton/ directory, Pipelines as Code automatically resolves the referenced task to provide a single pipeline run with an embedded spec in a PipelineRun object.

If Pipelines as Code cannot resolve the referenced tasks in the Pipeline or PipelineSpec definition, the run fails before applying any changes to the cluster. You can see the issue on your Git provider platform and inside the events of the target namespace where the Repository CR is located.

The resolver skips resolving if it observes the following type of tasks:

The resolver uses such tasks literally, without any transformation.

To test your pipeline run locally before sending it in a pull request, use the tkn pac resolve command.

You can also reference remote pipelines and tasks.

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 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 with a pull_request event that targets the main branch:

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

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:

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 a pipeline run with no events, such as sending a new commit to your branch or raising a pull request. On a GitHub App, go to the Checks tab and click Re-run.

If you target a pull or merge request, use the following comments inside your pull request to restart all or specific pipeline runs:

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

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 Pipelines as Code config map, if you set the error-detection-from-container-logs parameter to true, 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.

Whenever Pipelines as Code creates a new pipeline run in the target namespace, it creates or updates a secret with the pac-gitauth-<REPOSITORY_OWNER>-<REPOSITORY_NAME>-<RANDOM_STRING> format.

You must reference the secret with the basic-auth workspace in your pipeline run and pipeline definitions, which is then passed on to the git-clone task.

In the pipeline, you can reference the basic-auth workspace for the git-clone task to reuse:

You can modify this configuration by setting the secret-auto-create flag to either a false or true value, as required in the Pipelines as Code config map.

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.