Running the PipelineRun #
Pipelines-as-Code (PAC) can be used to run pipelines on events such as pushes
or pull requests. When an event occurs, PAC will try to match it to any
PipelineRuns located in the .tekton
directory of your repository
that are annotated with the appropriate event type.
The PipelineRuns definitions are fetched from the .tekton
directory at the
root of your repository from where the event comes from, this is unless you have
configured the provenance from the default
branch on your Repository
CR.
For example, if a PipelineRun has this annotation:
pipelinesascode.tekton.dev/on-event: "[pull_request]"
it will be automatically triggered and executed when a user with appropriate permissions submits a Pull Request. See ACL Permissions for triggering PipelineRuns below.
When using GitHub as a provider, Pipelines-as-Code runs on draft Pull Requests by default. However, you can prevent pipelines from triggering on draft Pull Requests by using the following annotation:
pipelinesascode.tekton.dev/on-cel-expression: event == "pull_request" && !body.pull_request.draft
With this configuration, your pipeline will only be triggered when the Pull Request is converted to “Ready for Review.” For additional examples, see Advanced event matching using CEL.
And if you are using the GitHub provider with GitHub Apps and have installed it on an organization, Pipelines-as-Code will only be triggered if it detects a Repo CR that matches one of the repositories in a URL on a repository that belongs to the organization where the GitHub App has been installed. Otherwise, Pipelines-as-Code will not be triggered.
ACL Permissions for triggering PipelineRuns #
The rules for determining whether a submitter is allowed to run a PipelineRun on CI are as follows. Any of the following conditions will allow a submitter to run a PipelineRun on CI:
- The author of the pull request is the owner of the repository.
- The author of the pull request is a collaborator on the repository.
- The author of the pull request is a public or private member of the organization that owns the repository.
- The author of the pull request has permissions to push to branches inside the repository.
- The author of the pull request is listed in the
OWNERS
file located in the main directory of the default branch on GitHub or your other service provider. (see below for the OWNERS file format).
If an unauthorized user attempts to trigger a PipelineRun through the creation
of a Pull Request or by any other means, Pipelines-as-Code will block the
execution and post a 'Pending'
status check. This check will inform the user
that they lack the necessary permissions. Only authorized users can initiate the
PipelineRun by commenting /ok-to-test
on the pull request.
GitHub bot users, identified through the GitHub API, are generally exempt from
the Pending
status check that would otherwise block a pull request. This
means the status check is silently ignored for bots unless they have been
explicitly authorized (using OWNERS file,
Policy or other means).
OWNERS file #
The OWNERS
file follows a specific format similar to the Prow OWNERS
file
format (detailed at https://www.kubernetes.dev/docs/guide/owners/). We
support a basic OWNERS
configuration with approvers
and reviewers
lists,
both of which have equal permissions for executing a PipelineRun
.
If the OWNERS
file uses filters
instead of a simple configuration, we only
consider the .*
filter and extract the approvers
and reviewers
lists from
it. Any other filters targeting specific files or directories are ignored.
Additionally, OWNERS_ALIASES
is supported and allows mapping alias names to
lists of usernames.
Including contributors in the approvers
or reviewers
lists within your
OWNERS
file grants them the ability to execute a PipelineRun
via
Pipelines-as-Code.
For example, if your repository’s main
or master
branch contains the
following approvers
section:
approvers:
- approved
The user with the username "approved"
will have the necessary
permissions.
PipelineRun Execution #
The PipelineRun will always run in the namespace of the Repository CRD associated with the repo that generated the event.
You can monitor the execution using the command line with the tkn pac CLI :
tkn pac logs -n my-pipeline-ci -L
If you need to show another pipelinerun than the last one you can use the tkn pac
logs command and it will ask you to select a PipelineRun attached to the
repository :
tkn pac logs -n my-pipeline-ci
If you have set-up Pipelines-as-Code with the Tekton Dashboard or on OpenShift using the OpenShift Console. Pipelines-as-Code will post a URL in the Checks tab for GitHub apps to let you click on it and follow the pipeline execution directly there.
Cancelling #
Cancelling in-progress PipelineRuns #
Cancelling in progress PipelineRuns is a Technology Preview feature only. Technology Preview features are not currently supported and might not be functionally complete. We do not recommend using them in production. These features provide early access to an upcoming Pipelines-as-Code features, enabling you to test functionality and provide feedback during the development process.
This feature is supported on the following providers
Git Provider Supported GitHub App ✅️ GitHub Webhook ✅️ Gitea ✅️ GitLab ✅️ Bitbucket Cloud ✅️ Bitbucket Data Center ❌️
You can choose to cancel a PipelineRun that is currently in progress. This can
be done by adding the annotation pipelinesascode.tekton.dev/cancel-in-progress: "true"
in the PipelineRun definition.
This feature is effective only when the PipelineRun
is in progress. If the
PipelineRun
has already completed or been cancelled, the cancellation will
have no effect. (see the max-keep-run annotation instead to clean old PipelineRuns
.)
The cancellation only applies to PipelineRuns
within the scope of the current
PullRequest
or the targeted branch for Push events. For example, if two
PullRequests
each have a PipelineRun
with the same name and the
cancel-in-progress annotation, only the PipelineRun
in the specific PullRequest
will be cancelled. This prevents interference between separate PullRequests.
Older PipelineRuns
are canceled only after the latest PipelineRun
is
successfully created and started. This annotation does not guarantee that only
one PipelineRun
will be active at a time.
If a PipelineRun
is in progress and the Pull Request is closed or declined,
the PipelineRun
will be canceled.
Currently, cancel-in-progress
cannot be used in conjunction with the concurrency
limit setting.
Cancelling a PipelineRun with a GitOps command #
See here
Restarting the PipelineRun #
You can restart a PipelineRun without having to send a new commit to your branch or pull_request.
GitHub APPS #
If you are using the GitHub apps method, you have the option to access the “Checks” tab where you can find an upper right button labeled “Re-Run”. By clicking on this button, you can trigger Pipelines-as-Code to respond and recommence testing the PipelineRun.
This feature enables you to either rerun a particular pipeline or execute the entire suite of checks once again.