Trigger PAC Pipelines

For Regular Users

This page explains how PAC starts PipelineRuns after a repository is connected. To define the .tekton/ files that PAC selects, see Define PipelineRuns in Git.

PAC triggers pipelines in three ways:

  • Automatic event triggers: a Git provider sends webhook events, and PAC matches those events against annotations on PipelineRun files.
  • Comment command triggers: an authorized user comments with a PAC command such as /test, /retest, or /cancel.
  • Incoming webhook triggers: an external system sends an HTTP POST request to the /incoming endpoint of the PAC controller for a Repository that has its own incoming rules. This page does not cover them; see Incoming Webhooks.

Automatic Event Triggers

Automatic triggers are controlled by annotations in each PipelineRun under .tekton/. PAC reads the PipelineRun definitions from the Git ref that raised the event, matches the annotations, replaces PAC variables, and creates the matching PipelineRuns in the Repository namespace. With pipelinerun_provenance: default_branch instead of the default source, PAC reads the definitions from the branch whose name is the repository's default branch (for example main), whichever branch a pull request or merge request comes from; see Source Branch Configuration.

The table below explains which event source to use. For exact annotation syntax and examples, see Trigger Events. The PAC event column shows the value that the on-event annotation matches; a custom comment is matched by the on-comment annotation instead. The {{ event_type }} variable can hold a different value for the same event, for example Merge Request or pull_request_labeled on GitLab; see Parameterizing Commits and URLs.

Event sourcePAC eventMatch condition
Branch pushpushThe pushed branch matches the PipelineRun branch filter.
Tag pushpushThe tag ref matches the PipelineRun tag filter.
Pull Request / Merge Requestpull_requestThe PR/MR base branch matches the PipelineRun branch filter.
Label updatepull_requestThe PR/MR has a matching label condition.
Custom PR/MR commenton-commentThe new PR/MR comment matches the PipelineRun comment regular expression.

Use custom comment triggers for repository-specific commands such as /deploy-preview. Use the built-in PAC commands below when you want PAC's native rerun, test, cancel, or approval behavior.

For more matching options, see the Pipelines as Code event matching documentation.

Comment Command Triggers

PAC also recognizes built-in GitOps commands in comments. These commands are useful when you want to run, rerun, approve, or cancel pipelines without pushing another commit.

Commands on Pull Requests and Merge Requests

Use these commands on an open PR or MR. They are shown with the default command prefix /. On GitHub, a Repository that sets settings.gitops_command_prefix to <prefix> accepts the built-in commands only in the form /<prefix> test, /<prefix> retest, and so on; GitLab uses / whatever the setting:

CommandEffect
/testRun all matching PipelineRuns for the current PR or MR.
/test <pipelinerun>Run only the named PipelineRun.
/retestRerun matching PipelineRuns that have no successful run for the same commit. PAC decides this from the PipelineRuns that still exist in the Repository namespace and, on GitLab, from the commit statuses of the commit; on GitHub, a run that the Pruner or a user deleted no longer counts.
/retest <pipelinerun>Rerun only the named PipelineRun.
/cancelCancel running PipelineRuns associated with the PR or MR.
/cancel <pipelinerun>Cancel only the named PipelineRun.
/ok-to-testAllow PAC to run CI for an external or otherwise untrusted contribution, when policy requires approval.
/ok-to-test <sha>Same as /ok-to-test, with explicit SHA validation when the PAC configuration requires it.

<pipelinerun> is the metadata.name or metadata.generateName value in the .tekton/ file, not the generated runtime name. For example, if the file has generateName: sv-event-pr-, use:

/test sv-event-pr-

Commands on Commit Comments

GitLab, and GitHub with a GitHub App, support /test, /retest, and /cancel on comments added to a pushed branch commit. In GitHub Webhook mode, PAC rejects every commit comment and creates no PipelineRun; comment on the pull request instead (see Provider Notes). /ok-to-test is for PR/MR authorization and does not apply to pushed commits.

When you comment on a commit, PAC must know which branch or tag context to use. If you do not specify one, PAC uses the repository default branch. The commented commit must be the HEAD commit of that branch, or the commit pointed to by the tag.

Use branch:<branch> when the commit belongs to a non-default branch:

/test <pipelinerun> branch:<branch>

Use tag:<tag> when the command should run in a tag context. This works on GitHub with a GitHub App (not in GitHub Webhook mode) and on GitLab. Add the comment to the commit that the tag points to. On GitLab, a comment on any other commit creates no PipelineRun, and the reason appears only in the PAC controller log, not as an event on the Repository; reading that log needs read access to Pod logs in the PAC namespace, usually a cluster administrator. In a tag context on GitLab, {{ source_branch }} and {{ target_branch }} are refs/tags/<tag>, and {{ git_tag }} is <tag>:

/test <pipelinerun> tag:<tag>

The same branch argument is accepted by /retest and /cancel. On GitHub tag comments, the tag argument is also accepted by both. On GitLab, /retest accepts the tag argument in the same way as /test:

/retest <pipelinerun> branch:<branch>
/cancel <pipelinerun> branch:<branch>
/retest <pipelinerun> tag:<tag>

Passing Parameters in Commands

Passing parameters in commands is Technology Preview. Built-in commands can include key=value arguments. PAC parses them from the comment and can use them to override custom parameters defined in Repository.spec.params or supported standard variables:

/test <pipelinerun> environment=staging
/test <pipelinerun> message="run smoke tests"

Only parameters already defined for the Repository or recognized by PAC are applied. Arbitrary keys are ignored.

Provider Notes

AreaGitHubGitLab
PR/MR eventPull Request events match the on-event value pull_request.Merge Request events match the on-event value pull_request; {{ event_type }} holds Merge Request or pull_request_labeled (see Parameterizing Commits and URLs).
PR/MR commentsBuilt-in commands and on-comment work on open Pull Requests.Built-in commands and on-comment work on open Merge Requests.
Commit commentsWith a GitHub App only. In GitHub Webhook mode, PAC rejects every commit comment with no github client has been initialized, exiting... (hint: did you forget setting a secret on your repo?) and creates no PipelineRun. With a GitHub App, /test, /retest, and /cancel work on commit comments. Other comments are matched against on-comment, and a matching PipelineRun runs on the repository default branch; a commit comment cannot select another branch this way.Only /test, /retest, and /cancel work on commit comments; other commit comments, including custom on-comment commands, are ignored.
Tag comment commandstag:<tag> works on commit comments with a GitHub App only, not in GitHub Webhook mode.tag:<tag> works with /test and /retest on commit comments. The commented commit must be the commit the tag points to.
/ok-to-test <sha>SHA validation is used when the PAC configuration requires it.The command is supported for MR authorization; SHA validation is a GitHub-specific safeguard.

For more command details, see the Pipelines as Code GitOps commands documentation.

Verify a Trigger

After an event or comment is sent, check the PipelineRuns in the namespace where the Repository CR is defined:

kubectl get pipelineruns -n <namespace>

If no PipelineRun is created, check the event annotations first. PAC records some reasons as events on the Repository, for example cannot find the targeted pipelinerun <pipelinerun> in this repository when /test names a PipelineRun that is not in .tekton/. Read them in the Repository namespace; events are kept only for a limited time, so check soon after the event:

kubectl describe repository <repository-name> -n <namespace>

An event that matches no PipelineRun, and a commit comment that PAC rejects, are not recorded on the Repository; their reasons are in the PAC controller log. Reading that log needs read access to Pod logs in the PAC namespace, usually a cluster administrator. With -l, kubectl logs prints only the last 10 lines unless --tail is set, so the command reads every line of the last 10 minutes; increase --since if the event is older:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --since=10m --tail=-1

Common checks:

SymptomCheck
No run after a pushThe file is under .tekton/, on-event includes push, and on-target-branch matches the pushed ref.
No run after a PR or MR updateon-event includes pull_request, and on-target-branch matches the PR/MR base branch.
/test <pipelinerun> does not matchUse the name or generateName from the .tekton/ file, not the generated runtime PipelineRun name.
Commit comment does not runOn GitHub, the repository is connected through a GitHub App: in GitHub Webhook mode, PAC rejects every commit comment (see Provider Notes). The commented commit is the HEAD of the selected branch: or the commit pointed to by tag:.
on-comment does not runThe new comment matches the regular expression after trimming leading and trailing spaces.

Platform Conventions

When to enable. Adopt this convention when several repositories share one PAC installation and contributors move between them. With the same commands in every repository, one set of instructions covers all projects instead of a different retry or branch-trigger procedure per repository.

Recommended values. Use /test <pipelinerun-name> branch:<branch> as the single command form, both in pull request or merge request comments and in commit comments. What branch: does depends on where the comment is posted. In a commit comment it selects the branch to run, and the commented commit must be the HEAD of that branch; name the branch explicitly instead of relying on the repository default branch (see Commands on Commit Comments). In a pull request or merge request comment, PAC always runs the source (head) branch of that pull request or merge request and ignores branch:, so write the source branch there to keep the one form. Running a different branch is possible only from a commit comment, and on GitHub only with a GitHub App: in GitHub Webhook mode, PAC rejects every commit comment, so contributors comment on the pull request there. The Provider Notes table explains why one built-in form is used everywhere: on GitLab, commit comments accept only /test, /retest, and /cancel, so custom on-comment commands work only in comments of an open merge request; on GitHub with a GitHub App, a custom on-comment command in a commit comment runs only on the repository default branch. With the default command prefix (see Commands on Pull Requests and Merge Requests), /test <pipelinerun-name> branch:<branch> is the one form that works in every place where PAC accepts comments, on both providers. <pipelinerun-name> is always the metadata.name or metadata.generateName from the .tekton/ file, not the generated runtime name, so give each PipelineRun a stable name that contributors can type. The rule for comment commands: to run or rerun a PipelineRun from .tekton/, and to select a branch from a commit comment, use the built-in /test or /retest; use on-comment only for other repository-specific actions, such as /deploy-preview (see Automatic Event Triggers). on-comment is Technology Preview.

Prerequisites. Comment events must reach PAC. With a webhook (GitLab, or GitHub in Webhook mode), automatic webhook registration subscribes to them, as listed in Configure GitLab Repository and Configure GitHub Repository; in GitHub Webhook mode, PAC still rejects commit comments, so there only pull request comments can trigger a PipelineRun. With a GitHub App, the App delivers the events instead and must subscribe to Commit comment and Issue comment, as listed in Create the GitHub App manually. The commenter must be authorized to run PAC commands, and for commit comments the commented commit must be the HEAD of the branch named in branch:<branch>.

Next Steps