Define PipelineRuns in Git
This guide is for regular users who define PAC PipelineRun manifests in Git repositories.
PAC reads Tekton PipelineRun manifests from .tekton/, matches them against Git events, and creates the matching PipelineRun in the namespace of the Repository CR.
TOC
Pipeline File LocationChoose a Pipeline Definition ScenarioDefine the Pipeline Inline withpipelineSpecReference a Pipeline with pipelineRefPipeline Defined in GitPipeline Defined in the ClusterTrigger EventsMatching a Pull Request EventMatching a Push EventMatching a Custom CommentMatching Pull Request LabelsBranch SpecificationBranch and Path FilteringAdvanced Event MatchingCancellation in ProgressParameterizing Commits and URLsTask ResolutionTroubleshootingConventions for Onboarding a RepositoryThree trigger patternsOne definition for merge requests and the main branchReference shared Pipeline templatesOnboarding self-checkNext StepsPipeline File Location
PAC processes all .yaml and .yml files under .tekton/:
Each PipelineRun is evaluated independently. If multiple files match the same event, PAC creates multiple PipelineRuns.
Choose a Pipeline Definition Scenario
Choose how the PipelineRun defines the work to run: inline with pipelineSpec, or by referencing a reusable Pipeline with pipelineRef.
Define the Pipeline Inline with pipelineSpec
Use pipelineSpec when the pipeline logic should live directly in the same Git file as the trigger definition:
Note: The samples on this page use the public alpine:latest image. Replace it with an image your cluster can pull, for example from an internal registry.
Note: The samples with an inline pipelineSpec or taskSpec, and the Pipelines and Tasks that PAC embeds with the default remote-tasks: "true" (see Pipeline Defined in Git and Task Resolution), assume that the cluster setting disable-inline-spec is empty. With pipelinerun in it, the Tekton webhook rejects a PipelineRun that has an inline pipelineSpec; see the warning in section 1 of Constrain Tekton Pipeline Execution with Kyverno.
Reference a Pipeline with pipelineRef
Use pipelineRef when the PipelineRun should reuse a Pipeline definition.
Pipeline Defined in Git
With the default remote-tasks: "true", a plain pipelineRef.name should reference a Pipeline that PAC can resolve from Git.
PAC checks the pipelinesascode.tekton.dev/pipeline annotation first, then Pipeline files under .tekton/ and its subdirectories.
Common layout:
pipeline.yaml:
pipelinerun.yaml:
For other Pipeline sources, use pipelinesascode.tekton.dev/pipeline.
See PAC Resolver and PAC pipeline resolution documentation.
Pipeline Defined in the Cluster
If the Pipeline is already managed in the cluster, for example by the platform Pipeline product, use one of these approaches.
Keep remote-tasks: "true" and reference the namespaced Pipeline with the Tekton cluster resolver:
Keep the namespace parameter unless the cluster resolver has a default namespace configured. If both this parameter and the resolver default namespace are empty, resolution fails.
Another option is for an administrator to set remote-tasks: "false" in the PAC component configuration.
In that mode, a plain pipelineRef.name can reference a Pipeline in the same namespace as the generated PipelineRun:
PAC does not inline or resolve the Pipeline in this mode. Tekton resolves the reference after PAC creates the PipelineRun, so the Pipeline must already exist in the target namespace.
Trigger Events
After you choose pipelineSpec or pipelineRef, add PAC annotations to control which Git events trigger the PipelineRun.
Matching a Pull Request Event
Matching a Push Event
Matching a Custom Comment
Use on-comment for repository-specific pull request or merge request commands. The value is a regular expression matched against a new comment after PAC trims leading and trailing spaces and newlines:
Because this example also sets on-event and on-target-branch, the PipelineRun also runs on every pull request or merge request open and update to main, not only on the /deploy-preview comment.
on-comment is Technology Preview. Use built-in GitOps commands such as /test, /retest, and /cancel when you want PAC's native command behavior instead of a repository-specific trigger.
Matching Pull Request Labels
Use on-label when a PipelineRun should run only for pull requests or merge requests that have a matching label:
on-label is Technology Preview. It still depends on on-event and on-target-branch. It is supported for GitHub, Gitea, and GitLab repositories, but not for Bitbucket repositories.
Branch Specification
on-target-branch accepts full refs, branch names, tags, globs, and comma-separated values.
Branch and Path Filtering
Use branch annotations for simple filtering:
Path-change annotations are Technology Preview. If on-cel-expression is set, PAC ignores on-path-change and on-path-change-ignore.
A PipelineRun with a path filter does not start when the same event also changes a file under the on-path-change-ignore paths, even if other changed files match on-path-change.
On GitLab, PAC reads the changed files of a merge request through the merge request diffs API (GET /projects/:id/merge_requests/:iid/diffs). If the GitLab instance does not provide this API (for example, GitLab 14.0.12 returns 404 Not Found for it), PAC logs error getting changed files: 404 Not Found for every merge request event and merge request comment, and a PipelineRun with a path filter never starts for a merge request. Runs without path filters are still created, and path filters on push events are not affected.
Advanced Event Matching
Use pipelinesascode.tekton.dev/on-cel-expression for complex conditions. When CEL is set, PAC uses the CEL expression and ignores on-target-branch, on-event, on-label, on-path-change, and on-path-change-ignore.
Common CEL fields include event, event_title, target_branch, source_branch, target_url, source_url, files.all, files.added, files.deleted, files.modified, files.renamed, body, and headers.
Cancellation in Progress
Use pipelinesascode.tekton.dev/cancel-in-progress: "true" to cancel older runs of the same PipelineRun when a new one starts. When a new run starts, PAC cancels only runs that have not finished, in the same namespace, of the same repository and with the same PipelineRun name in .tekton/: for a pull request event, only the runs of the same pull request; for a push event, only the runs whose source branch is the pushed branch, so a push to another branch leaves them running. This cancellation by a new run works only when the Repository has no concurrency_limit, set on it or inherited from a global Repository. With a limit, a new run does not cancel the older runs, and PAC records the event error cancelling in progress pipelineRuns: cancel in progress is not supported with concurrency limit on the Repository (see it with kubectl describe repository <name> -n <namespace>).
Closing a pull request or merge request also cancels its unfinished runs in the Repository namespace that have cancel-in-progress: "true" and were started by opening, reopening or updating it, by a built-in GitOps command on it or by an on-comment comment on it, whatever their PipelineRun name and also when the Repository has a concurrency_limit. On GitLab, merging a merge request does not cancel these runs. Runs started by a label change on the pull request or merge request (their pipelinesascode.tekton.dev/event-type label is pull_request_labeled) are not cancelled by closing it. cancel-in-progress is Technology Preview.
Parameterizing Commits and URLs
PAC replaces dynamic variables in the {{ variable_name }} format before creating the PipelineRun. Tekton parameters such as $(params.name) are handled later by Tekton.
Example:
PAC fills {{ git_auth_secret }} with a generated Secret name for every event. It creates that Secret for the run from the Git provider token that the Repository uses (the GitHub App installation token with a GitHub App), while the PAC setting secret-auto-create is "true" (the default). With "false", the name is still filled, but no Secret of that name exists.
Task Resolution
PAC can embed tasks referenced by PAC annotations, or you can use Tekton resolver syntax directly.
PAC embeds the Task named in pipelinesascode.tekton.dev/task only with the default remote-tasks: "true". With remote-tasks: "false", PAC ignores the task annotations, and Tekton looks for a Task named git-clone in the namespace of the PipelineRun.
See PAC Resolver for supported task and Pipeline sources.
Troubleshooting
Useful checks. 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/; kubectl describe repository shows 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 is not recorded on the Repository; its reason is in the PAC controller log, and 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 last command reads every line of the last 10 minutes; increase --since if the event is older:
Conventions for Onboarding a Repository
The conventions below apply when a platform team onboards many repositories onto shared Pipeline templates. They narrow the options described on this page; repositories that maintain their own pipelines can keep using pipelineSpec or a Pipeline defined in Git. For the onboarding steps themselves, follow Configure GitLab Repository or Configure GitHub Repository.
Three trigger patterns
Path-change annotations and on-comment are Technology Preview. Keep on-comment for repository-specific actions such as /deploy-preview; for running and rerunning pipelines, use the built-in commands as described in Trigger PAC Pipelines. If on-cel-expression is set, PAC ignores on-event, on-target-branch, and the path filters. On GitLab, path filters on merge request events need the merge request diffs API; see Branch and Path Filtering.
One definition for merge requests and the main branch
Use one PipelineRun definition for both pull requests or merge requests and pushes to the main branch, instead of two copies that drift apart. Set on-event to both events and on-target-branch to the branch: for pull_request, PAC matches the base branch; for push, it matches the pushed branch. When the shared Pipeline must run push-only steps, such as publishing, only for the main branch, pass {{ source_branch }}, {{ source_url }}, and {{ repo_url }} as parameters and run those steps only when the source branch is the main branch and the source repository is the repository itself. Do not key them on {{ event_type }}: on GitLab a merge request event renders it as Merge Request, and /test and /retest comments render it as pull_request, also when a commit comment reruns the main branch.
In the shared Pipeline, declare the parameters and guard the push-only Task with two when expressions; the Task runs only when both are true:
Reference shared Pipeline templates
A PipelineRun under .tekton/ references a shared Pipeline template through pipelineRef.resolver: cluster for a Pipeline managed in a cluster namespace (see Reference a Pipeline with pipelineRef), hub for a versioned catalog Pipeline, or git for a Pipeline stored in a template repository (see Resolvers). To select a template version, set the version parameter for the hub resolver or the revision parameter for the git resolver. For the git resolver, revision can be a branch, tag, or commit (see Resolvers); only a commit SHA pins the content, so that moving to a new template version is a change to .tekton/. A branch, or a tag that can be moved, resolves to new content without any change to .tekton/. For the hub resolver, version names a published catalog version; whether its content can change after publication depends on how the catalog is maintained, so confirm this with the catalog administrator before you rely on it as a pin. The cluster resolver takes kind, name, and namespace (plus an optional cache mode) and has no version parameter.
The hub example also sets catalog, the name of the catalog to read from. Built-in Pipelines are served from catalog-pipelines and built-in Tasks from catalog (see Resolvers); an older Pipeline reference that uses catalog: catalog still resolves through a compatibility alias, but new Pipeline references should use catalog-pipelines. Replace it with the catalog name configured in your cluster if it differs. Keep catalog, kind, name, and version in every hub reference: in a namespace that enforces the require-hub-reference-shape rule of Constrain Tekton Pipeline Execution with Kyverno, a PipelineRun whose hub reference leaves any of them empty or sets a kind other than pipeline is rejected. That rule also rejects a PipelineRun whose resolver is not hub, so the cluster and git forms are rejected in such a namespace.
Do not use a bare pipelineRef.name for platform templates. With the default remote-tasks: "true", PAC resolves such a reference from the pipelinesascode.tekton.dev/pipeline annotation or from .tekton/ and embeds the resolved Pipeline into the generated PipelineRun as an inline pipelineSpec, and a Pipeline that exists only in the cluster is not found. The resolver form is handled by Tekton rather than PAC, so the generated PipelineRun keeps its reference to the template. This also keeps runs compatible with an admission policy that rejects inline pipelineSpec, such as the deny-pipelinerun-inline-pipelinespec rule in Constrain Tekton Pipeline Execution with Kyverno; the resolver rules of that guide additionally require the hub resolver.
Onboarding self-check
After onboarding a repository, confirm each item. Items marked Webhook mode apply to a repository connected with a token and a webhook (GitLab, or GitHub in Webhook mode); items marked GitHub App mode apply to a GitHub repository connected through a GitHub App, which needs no per-repository Secret or webhook (see Configure GitHub Repository).
- A
RepositoryCR exists in the project namespace and itsspec.urlmatches the repository. - Webhook mode:
spec.git_provider.secretandspec.git_provider.webhook_secretreference a Secret in the same namespace that carriesprovider.tokenandwebhook.secret, or the Repository has agit_providerblock without them and inherits both from the global Repository CR, whose Secret is in the PAC namespace; see Create a Git Secret for PAC and Creating a Global Repository CR. - Webhook mode: the webhook is active: the
pac.tekton.alauda.io/webhook-registration-statusannotation on theRepositoryisRegistered, or the webhook was added through the manual fallback in the repository guide. If the status isFailed, read thepac.tekton.alauda.io/webhook-registration-reasonannotation: aFailedRepository can still have an active webhook from an earlier registration. - GitHub App mode: the repository is included in the GitHub App installation, and the
pipelines-as-code-secretSecret in the PAC namespace holds the App ID, private key, and webhook secret; see Integration mode 1: GitHub App. - Each
PipelineRununder.tekton/hason-eventandon-target-branchvalues that match the events and branches the repository uses. - Each
spec.pipelineRefuses theresolverform, not a barename, and selects the template version where the resolver supports it:versionforhub, and forgitarevisionthat is a commit SHA (a branch or a movable tag does not pin the content). - Each
PipelineRununder.tekton/runs on the first event of its trigger pattern (see Three trigger patterns): an event-driven one on a matching push or pull request or merge request update, a comment-driven one on a/test <pipelinerun-name> branch:<branch>comment, and one with a path filter on a matching event that changes a file under the filtered paths and no file under itson-path-change-ignorepaths (if the same event also changes an ignored file, the run does not start). The run is listed bykubectl get pipelineruns -n <namespace> -l pipelinesascode.tekton.dev/repository=<repository-name>, and the Git provider shows its result: a commit status in Webhook mode, or a Check Run on the commit in GitHub App mode. - A
/test <pipelinerun-name> branch:<source-branch>comment on a merge request starts a new run of the merge request's source branch.
Next Steps
- PAC Resolver - Remote task and Pipeline sources
- PAC documentation - Pipelines as Code documentation
- Trigger PAC Pipelines - Automatic events and comment commands
- Guides - Repository setup walkthroughs
- Common Issues - Troubleshooting guide