Trigger PAC Pipelines
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
PipelineRunfiles. - 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
/incomingendpoint of the PAC controller for aRepositorythat has its ownincomingrules. This page does not cover them; see Incoming Webhooks.
TOC
Automatic Event TriggersComment Command TriggersCommands on Pull Requests and Merge RequestsCommands on Commit CommentsPassing Parameters in CommandsProvider NotesVerify a TriggerPlatform ConventionsNext StepsAutomatic 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.
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:
<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:
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:
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>:
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:
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:
Only parameters already defined for the Repository or recognized by PAC are applied. Arbitrary keys are ignored.
Provider Notes
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:
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:
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:
Common checks:
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
- Define PipelineRuns in Git - PipelineRun files and trigger annotations
- Incoming Webhooks - Direct HTTP triggers for external systems
- Common Issues - Troubleshooting guide