Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Managing pipeline runs

6.1. Verifying a pipeline run

You can verify that the Pipelines as Code resolver correctly processes the pipeline run definition that you created.

Prerequisites

  • You installed the tkn command line utility.
  • You are logged into your OpenShift Container Platform cluster using OpenShift CLI (oc).
  • You cloned your Git repository locally.

Procedure

  • From the root of your cloned Git repository, run the following command, specifying your pipeline run definition file name: 

    $ tkn pac resolve .tekton/pipeline-run-definition.yaml
    Copy to clipboard

    This command processes the pipeline run definition using the Pipelines as Code resolver. If the resolver fails to find any referenced resource, the output displays an error message. If the resolver completes successfully, the output displays the definition of a PipelineRun custom resource (CR) that includes all referenced resources, such as remote task definitions.

6.2. Running a pipeline run using Pipelines as Code

With default configuration, Pipelines as Code runs any pipeline run in the .tekton/ directory of the default branch of repository, when specified events such as pull request or push occurs on the repository. For example, if a pipeline run on the default branch has the annotation pipelinesascode.tekton.dev/on-event: "[pull_request]", it will run whenever a pull request event occurs.

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:

  • The author is the owner of the repository.
  • The author is a collaborator on the repository.
  • The author is a public member on the organization of the repository.
  • The pull request author is listed in the approvers or reviewers section of the OWNERS file in the root of the repository, as defined in the Kubernetes documentation. Pipelines as Code supports the specification for the OWNERS and OWNERS_ALIASES files. If the OWNERS file includes a filters section, Pipelines as Code matches approvers and reviewers only against the .* filter.

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.

Pipeline run execution

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.

  • To follow the execution of the last pipeline run, use the following example: 

    $ tkn pac logs -n <my-pipeline-ci> -L 1
    Copy to clipboard
    1
    my-pipeline-ci is the namespace for the Repository CRD.

  • To follow the execution of any pipeline run interactively, use the following example: 

    $ tkn pac logs -n <my-pipeline-ci> 1
    Copy to clipboard
    1
    my-pipeline-ci is the namespace for the Repository CRD. If you need to view a pipeline run other than the last one, you can use the tkn pac logs command to select a PipelineRun attached to the repository:

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.

6.3. Restarting or canceling a pipeline run using Pipelines as Code

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:

  • The /test and /retest comment restarts all pipeline runs.
  • The /test <pipeline_run_name> and /retest <pipeline_run_name> comment starts or restarts a specific pipeline run. You can use this command to start any Pipelines as Code pipeline run on the repository, whether or not it was triggered by an event for this pipeline run.

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

  • The /cancel comment cancels all pipeline runs.
  • The /cancel <pipeline_run_name> comment cancels a specific pipeline run.

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:

  • The author is the owner of the repository.
  • The author is a collaborator on the repository.
  • The author is a public member on the organization of the repository.
  • The comment author is listed in the approvers or reviewers section of the OWNERS file in the root of the repository, as defined in the Kubernetes documentation. Pipelines as Code supports the specification for the OWNERS and OWNERS_ALIASES files. If the OWNERS file includes a filters section, Pipelines as Code matches approvers and reviewers only against the .* filter.
Important

Using a comment to start a pipeline run that does not match an event is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Procedure

  • If you target a pull request and you use the GitHub App, go to the Checks tab and click Re-run all checks.

  • If you target a pull or merge request, use the comments inside your pull request:

    Example comment that cancels all pipeline runs

    This is a comment inside a pull request.
/cancel

  • If you target a push request, include the comments within your commit messages.

    Note

    This feature is supported for the GitHub provider only.

    1. Go to your GitHub repository.
    2. Click the Commits section.
    3. Click the commit where you want to restart a pipeline run.

    4. Click on the line number where you want to add a comment.

      Example comment that starts or restarts a specific pipeline run

      This is a comment inside a commit.
/retest example_pipeline_run

      Note

      If you run a command on a commit that exists in multiple branches within a push request, the branch with the latest commit is used.

      This results in two situations:

      • If you run a command on a commit without any argument, such as /test, the test is automatically performed on the main branch.
      • If you include a branch specification, such as /test branch:user-branch, the test is performed on the commit where the comment is located with the context of the user-branch branch.

6.4. Monitoring pipeline run status using Pipelines as Code

Depending on the context and supported tools, you can monitor the status of a pipeline run in different ways.

Status on GitHub Apps

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.

Log error snippet

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.

Note

Pipelines as Code avoids leaking secrets by looking into the pipeline run and replacing secret values with hidden characters. However, Pipelines as Code cannot hide secrets coming from workspaces and envFrom source.

Annotations for log error snippets

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.

Important

Adding annotations for log error snippets is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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

<filename>:<line>:<column>: <error message>
Copy to clipboard

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.

Note

By default, Pipelines as Code scans only the last 50 lines of the container logs. You can increase this value in the error-detection-max-number-of-lines field or set -1 for an unlimited number of lines. However, such configurations may increase the memory usage of the watcher.

Status for webhook

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

Failures

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.

Status associated with Repository CRD

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

$ oc get repo -n <pipelines-as-code-ci>
Copy to clipboard
NAME                  URL                                                        NAMESPACE             SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
pipelines-as-code-ci   https://github.com/openshift-pipelines/pipelines-as-code   pipelines-as-code-ci   True        Succeeded   59m         56m
Copy to clipboard

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

Notifications

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

Additional resources

Additional resources

6.5. Cleaning up pipeline run using Pipelines as Code

There can be many pipeline runs in a user namespace. By setting the max-keep-runs annotation, you can configure Pipelines as Code to retain a limited number of pipeline runs that matches an event. For example: 

...
  pipelinesascode.tekton.dev/max-keep-runs: "<max_number>" 1
...
Copy to clipboard
1
Pipelines as Code starts cleaning up right after it finishes a successful execution, retaining only the maximum number of pipeline runs configured using the annotation.
Note
  • Pipelines as Code skips cleaning the running pipelines but cleans up the pipeline runs with an unknown status.
  • Pipelines as Code skips cleaning a failed pull request.

6.6. Using incoming webhook with Pipelines as Code

Using an incoming webhook URL and a shared secret, you can start a pipeline run in a repository.

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

  • The incoming webhook URL that Pipelines as Code matches.

  • The Git provider and the user token. Currently, Pipelines as Code supports github, gitlab, and bitbucket-cloud.

    Note

    When using incoming webhook URLs in the context of GitHub app, you must specify the token.

  • The target branches and a secret for the incoming webhook URL.

Example: Repository CRD with incoming webhook

apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: repo
  namespace: ns
spec:
  url: "https://github.com/owner/repo"
  git_provider:
    type: github
    secret:
      name: "owner-token"
  incoming:
    - targets:
      - main
      secret:
        name: repo-incoming-secret
      type: webhook-url
Copy to clipboard

Example: The repo-incoming-secret secret for incoming webhook

apiVersion: v1
kind: Secret
metadata:
  name: repo-incoming-secret
  namespace: ns
type: Opaque
stringData:
  secret: <very-secure-shared-secret>
Copy to clipboard

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

$ curl -X POST 'https://control.pac.url/incoming?secret=very-secure-shared-secret&repository=repo&branch=main&pipelinerun=target_pipelinerun'
Copy to clipboard

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.

6.7. Additional resources

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.