Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

Chapter 6. Managing pipeline runs

6.1. Verifying a pipeline run
Copiar o link

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 Toggle word wrap

    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
Copiar o link

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 or in a discussion thread reply to 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 Toggle word wrap
    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 Toggle word wrap
    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. Triggering a PipelineRun on Git tags
Copiar o link

When you create or reference a Git tag in a repository that is integrated with Pipelines as Code, you can trigger a PipelineRun on a tag via GitOps comment. This capability enables you to test or deploy tagged versions of your code, supporting release-based workflows and version control practices.

Pipelines as Code resolves the Git tag to its corresponding commit SHA and runs the PipelineRun defined for that commit. You can initiate or manage such runs by commenting on the tagged commit using supported GitOps commands.

Triggering PipelineRun on Git tags is supported for GitHub App, GitHub Webhook, and GitLab integrations. This functionality is not currently available for Gitea, Bitbucket Cloud, or Bitbucket Data Center.

6.3.1. Supported GitOps commands
Copiar o link

  • /test tag:<tag>:: Retrigger all matching PipelineRun for the tag commit
  • /test <pipelinerun-name> tag:<tag>:: Retrigger only the named PipelineRun
  • /retest tag:<tag>:: Retrigger all matching PipelineRun for the tag commit
  • /retest <pipelinerun-name> tag:<tag>:: Retrigger only the named PipelineRun
  • /cancel tag:<tag>:: Cancel all running PipelineRun for the tag commit
  • /cancel <pipelinerun-name> tag:<tag>:: Cancel only the named PipelineRun

A PipelineRun configured to respond to tag events typically includes annotations such as pipelinesascode.tekton.dev/on-target-branch: "[refs/tags/*]" and pipelinesascode.tekton.dev/on-event: "[push]". These annotations ensure that tag creation events are recognized as push events and processed correctly. When a tag is created or referenced, Pipelines as Code treats it as a push event and uses the resolved commit SHA to run the associated PipelineRun. The same logic applies to subsequent GitOps commands added as comments on the tagged commit.

Tag based triggering is particularly useful in continuous delivery scenarios where specific versions or releases are represented by tags. This method enables you to validate and promote release artifacts consistently without modifying the branch state.

The following example shows a minimal PipelineRun configuration that triggers on tag events: 

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun-on-tag
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/tags/*]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
      - name: tag-task
        taskSpec:
          steps:
            - name: echo
              image: registry.access.redhat.com/ubi9/ubi-micro
              script: |
                echo "tag: {{ git_tag }}"
Copy to Clipboard Toggle word wrap

6.3.2. Triggering PipelineRuns for GitOps commands using tagged commits
Copiar o link

You can trigger a PipelineRun using a Git tag for tagged commits.

Procedure

  1. Open your GitHub repository.
  2. Navigate to the Tags view or the Releases section.
  3. Select the required tag, for example v1.0.0, to view its associated commit.
  4. Click the commit SHA for the selected tag.
  5. In the comment field of the commit, enter a supported GitOps command, such as /test tag:v1.0.0 or /cancel tag:v1.0.0.
  6. Verify that Pipelines as Code processes the comment and triggers or updates the corresponding PipelineRun.

6.4. Restarting or canceling a pipeline run using Pipelines as Code
Copiar o link

You can restart or cancel a pipeline run without triggering an event, such as sending a new commit to a branch or creating 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 comments restart all pipeline runs.
  • The /test <pipeline_run_name> and /retest <pipeline_run_name> comments start or restart a specific pipeline run. You can use these commands 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 of the organization that owns 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
    Copy to Clipboard Toggle word wrap

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

    Note

    This feature is supported for the GitHub and GitLab providers only.

    1. Go to your GitHub or GitLab repository.
    2. In GitHub, click the Commits section. In GitLab, click the History 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. The following example shows a comment that starts or restarts a specific pipeline run: 

      This is a comment inside a commit.
/retest example_pipeline_run
      Copy to Clipboard Toggle word wrap
      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.5. Monitoring pipeline run status using Pipelines as Code
Copiar o link

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 Toggle word wrap

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.

YAML parting error messages in pull request comments

Pipelines as Code detects and reports YAML errors in PipelineRun definitions within the .tekton directory. When an invalid PipelineRun YAML is found in a pull request (PR) event, Pipelines as Code creates a comment on the pull request (PR) describing the error and halts the execution of other correctly formatted pipeline runs. Consider the following scenarios:

  • If the PR is updated and new YAML errors are detected, the comment is updated with the latest information.
  • If no new errors are found, the existing comment remains unchanged and is not deleted.
  • If a validation issue is found, Pipelines as Code logs the error in the user namespace events log and the Pipelines as Code controller log.

These error scenarios do not halt the execution of valid pipeline runs because the system continues to process validated and matched pipeline runs, preventing a single validation problem from disrupting the entire automation workflow.

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 Toggle word wrap 
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 Toggle word wrap

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.6. Cleaning up pipeline run using Pipelines as Code
Copiar o link

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 Toggle word wrap
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.7. Using incoming webhook with Pipelines as Code
Copiar o link

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 Toggle word wrap

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 Toggle word wrap

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 Toggle word wrap

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.

Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2026 Red HatVoltar ao topo