You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
= Annotations for matching events to a pipeline run
7
7
8
-
[role="_abstract"]
9
-
To run pipelines using {pac}, you can create pipeline run definitions or templates as YAML files in the `.tekton/` directory of the repository. You can reference YAML files in other repositories using remote URLs, but pipeline runs are only triggered by events in the repository containing the `.tekton/` directory.
8
+
You can match different Git provider events with each pipeline run by using annotations on the pipeline run. If there are multiple pipeline runs matching an event, {pac} runs them in parallel and posts the results to the Git provider as soon as a pipeline run finishes.
10
9
11
-
The {pac} resolver bundles the pipeline runs with all tasks as a single pipeline run without external dependencies.
12
-
13
-
[NOTE]
14
-
====
15
-
* For pipelines, use at least one pipeline run with a spec, or a separated `Pipeline` object.
16
-
* For tasks, embed task spec inside a pipeline, or define it separately as a Task object.
17
-
====
18
-
19
-
[discrete]
20
-
.Parameterizing commits and URLs
21
-
22
-
You can specify the parameters of your commit and URL by using dynamic, expandable variables with the {{<var>}} format. Currently, you can use the following variables:
23
-
24
-
* `{{repo_owner}}`: The repository owner.
25
-
* `{{repo_name}}`: The repository name.
26
-
* `{{repo_url}}`: The repository full URL.
27
-
* `{{revision}}`: Full SHA revision of a commit.
28
-
* `{{sender}}`: The username or account id of the sender of the commit.
29
-
* `{{source_branch}}`: The branch name where the event originated.
30
-
* `{{target_branch}}`: The branch name that the event targets. For push events, it's the same as the `source_branch`.
31
-
* `{{pull_request_number}}`: The pull or merge request number, defined only for a `pull_request` event type.
32
-
* `{{git_auth_secret}}`: The secret name that is generated automatically with Git provider's token for checking out private repos.
33
-
34
-
[discrete]
35
-
.Matching an event to a pipeline run
36
-
37
-
You can match different Git provider events with each pipeline run by using special annotations on the pipeline run. If there are multiple pipeline runs matching an event, {pac} runs them in parallel and posts the results to the Git provider as soon a pipeline run finishes.
<1> You can specify multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following:
26
+
<1> You can specify multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following items:
56
27
* Full references to branches such as `"refs/heads/main"`
57
28
* Globs with pattern matching such as `"refs/heads/\*"`
You can use the following example to match the `pipeline-push-on-main` pipeline run with a `push` event targeting the `refs/heads/main` branch:
64
35
@@ -73,13 +44,17 @@ annotations:
73
44
pipelinesascode.tekton.dev/on-event: "[push]"
74
45
# ...
75
46
----
76
-
<1> You can specify multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following:
47
+
<1> You can specify multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following items:
77
48
* Full references to branches such as `"refs/heads/main"`
78
49
* Globs with pattern matching such as `"refs/heads/\*"`
== Matching a pull request label to a pipeline run
54
+
55
+
:FeatureName: Matching pull request labels to a pipeline run
56
+
include::snippets/technology-preview.adoc[]
57
+
83
58
84
59
// Note for reviewers: passive voice unfortunately seems to be necessary in the following paragraph. A label can be added to a pull request by an automated system as well as a user, so there is no subject to mention. The same applies to updating the PR with a new commit
85
60
@@ -103,11 +78,11 @@ annotations:
103
78
The current version of {pac} supports matching events to pull request labels only for the GitHub, Gitea, and GitLab repository hosting service providers.
104
79
====
105
80
106
-
:FeatureName: Matching pull request labels a pipelinerun
:FeatureName: Matching a comment event to a pipeline run
85
+
include::snippets/technology-preview.adoc[]
111
86
112
87
You can use the following example to match the `pipeline-comment` pipeline run with a comment on a pull request, when the text of the comment matches the `^/merge-pr` regular expression:
113
88
@@ -129,11 +104,8 @@ The pipeline run starts only if the comment author meets one of the following re
129
104
* The author is a public member on the organization of the repository.
130
105
* 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 https://www.kubernetes.dev/docs/guide/owners/[Kubernetes documentation]. {pac} supports the specification for the `OWNERS` and `OWNERS_ALIASES` files. If the `OWNERS` file includes a https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#filters[filters] section, {pac} matches approvers and reviewers only against the `.*` filter.
131
106
132
-
:FeatureName: Matching a comment event to a pipeline run
{pac} supports using Common Expression Language (CEL) based filtering for advanced event matching. If you have the `pipelinesascode.tekton.dev/on-cel-expression` annotation in your pipeline run, {pac} uses the CEL expression and skips the `on-target-branch` annotation. Compared to the simple `on-target-branch` annotation matching, the CEL expressions allow complex filtering and negation.
139
111
@@ -230,53 +202,12 @@ metadata:
230
202
231
203
[NOTE]
232
204
====
233
-
If you use the `header` or `body` field for event matching, you might be unable to trigger the pipeline run using Git commands such as `retest`. If you use a Git command, the payload body is the comment that contains this command and not the original payload.
205
+
If you use the `header` or `body` field for event matching, you might be unable to trigger the pipeline run using Git commands such as `retest`. If you use a Git command, the payload body is the comment that contains this command, and not the original payload.
234
206
235
-
If you want to trigger the pipeline run again when using the `body` field for event matching, you can close and reopen the pull request or merge request, or alternatively add a new SHA commit, for example using the following command:
207
+
If you want to trigger the pipeline run again when using the `body` field for event matching, you can close and reopen the pull request or merge request, or alternatively add a new SHA commit. You can add a new SHA commit by using the following command:
.Using the temporary GitHub App token for Github API operations
245
-
246
-
You can use the temporary installation token generated by {pac} from GitHub App to access the GitHub API. The token value is stored in the temporary `{{git_auth_secret}}` dynamic variable generated for private repositories in the `git-provider-token` key.
247
-
248
-
For example, to add a comment to a pull request, you can use the `github-add-comment` task from {tekton-hub} using a {pac} annotation:
<1> By using the dynamic variables, you can reuse this snippet template for any pull request from any repository.
278
-
279
-
[NOTE]
280
-
====
281
-
On GitHub Apps, the generated installation token is available for 8 hours and scoped to the repository from where the events originate unless configured differently on the cluster.
You can use parameters in a pipeline run specification to provide information about the commit that triggered the pipeline run and to use the temporary GitHub App token for Github API operations.
You can specify the parameters of your commit and URL by using dynamic, expandable variables with the `{{<var>}}` format. Currently, you can use the following variables:
14
+
15
+
* `{{repo_owner}}`: The repository owner.
16
+
* `{{repo_name}}`: The repository name.
17
+
* `{{repo_url}}`: The repository full URL.
18
+
* `{{revision}}`: Full SHA revision of a commit.
19
+
* `{{sender}}`: The username or account ID of the sender of the commit.
20
+
* `{{source_branch}}`: The branch name where the event originated.
21
+
* `{{target_branch}}`: The branch name that the event targets. For push events, it is the same as the `source_branch`.
22
+
* `{{pull_request_number}}`: The pull or merge request number, defined only for a `pull_request` event type.
23
+
* `{{git_auth_secret}}`: The secret name that is generated automatically with the Git provider token for checking out private repos.
== Temporary GitHub App token for GitHub API operations
27
+
28
+
You can use the temporary installation token generated by {pac} from the GitHub App to access the GitHub API. The GitHub App generates a key for private repositories in the `git-provider-token` key. You can use the `{{git_auth_secret}}` dynamic variable in pipeline runs to access this key.
29
+
30
+
For example, if your pipeline run must add a comment to a pull request, you can use the a {pac} annotation to fetch the `github-add-comment` task definition from {tekton-hub}, and then define the task that adds the comment, as shown in the following example:
<1> By using the dynamic variables, you can reuse this snippet template for any pull request from any repository that you use with {pac}.
57
+
58
+
[NOTE]
59
+
====
60
+
On GitHub Apps, the generated installation token is available for 8 hours and scoped to the repository from where the events originate. You can configure the scope differently, but the expiration time is determined by GitHub.
= Parameters and annotations in a {pac} pipeline run
7
+
8
+
// Note for reviewers: some of the information in this file is to be moved into a separate procedure in the next pull request, which will require a separate review cycle.
9
+
10
+
[role="_abstract"]
11
+
To run pipelines using {pac}, you can create pipeline run definitions or templates as YAML files in the `.tekton/` directory of your Git repository. You can reference YAML files in other repositories using remote URLs, but pipeline runs are triggered only by events in the repository containing the `.tekton/` directory.
12
+
13
+
The {pac} resolver bundles the pipeline runs with all tasks as a single pipeline run without external dependencies.
14
+
15
+
In addition to features that exist in all {openshift-pipelines} pipeline runs, you can use additional parameters and annotations in pipeline run files for {pac}.
16
+
17
+
[NOTE]
18
+
====
19
+
* For pipelines, use at least one pipeline run with a spec, or a separated `Pipeline` object.
20
+
* For tasks, embed the task specification inside a pipeline, or define it separately as a Task object.
= Annotations for specifying automatic cancellation-in-progress for a pipeline run
7
+
8
+
By default, {pac} does not cancel pipeline runs automatically. Every pipeline run that {pac} creates and starts executes until it completes. However, events that trigger pipeline runs can come in quick succession. For example, if a pull request triggers a pipeline run and then the user pushes new commits into the pull request source branch, each push triggers a new copy of the pipeline run. If several pushes happen, several copies can run, which can consume excessive cluster resources.
9
+
10
+
You can configure a pipeline run to enable automatic cancellation-in-progress. If you enable automatic cancellation for a pipeline run, {pac} cancels the pipeline run in the following situations:
11
+
12
+
* {pac} has successfully started a copy of the same pipeline run for the same pull request or the same source branch.
13
+
14
+
* The pull request that triggered the pipeline run is merged or closed.
15
+
16
+
You can use the following example to enable automatic cancellation when you create the `sample-pipeline` pipeline run:
{pac} cancels a pipeline run _after_ starting a new copy of this pipeline run successfully. The `pipelinesascode.tekton.dev/cancel-in-progress` setting does _not_ ensure that only one copy of the pipeline run is executing at any time.
32
+
====
33
+
34
+
:FeatureName: Automatic cancellation-in-progress of pipeline runs
* xref:../pac/using-pipelines-as-code-repos.adoc#scoping-github-token_using-pipelines-as-code-repos[Scoping the GitHub token to additional repositories]
* link:https://github.com/openshift-pipelines/pipelines-as-code/tree/main/.tekton[An example of the `.tekton/` directory in the Pipelines as Code repository]
0 commit comments