Skip to content

Commit c8f9fc9

Browse files
michaelryanpetermichaelryanpeter
authored
Merge pull request #93153 from openshift-cherrypick-robot/cherry-pick-89926-to-pipelines-docs-1.19
[pipelines-docs-1.19] RHDEVDOCS 6385 procedure for PAC pipeline runs
2 parents 1a4d7aa + a2d71b8 commit c8f9fc9

14 files changed

+323
-132
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,8 +94,8 @@ Topics:
9494
File: using-pipelines-as-code-repos
9595
- Name: Using the Repository custom resource
9696
File: using-repository-crd
97-
- Name: Using the Pipelines as Code resolver
98-
File: using-pac-resolver
97+
- Name: Creating pipeline runs in Pipelines as Code
98+
File: creating-pipeline-runs-pac
9999
- Name: Managing pipeline runs
100100
File: managing-pipeline-runs-pac
101101
- Name: Pipelines as Code command reference

‎modules/op-creating-pipeline-run-pac.adoc

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
// This module is included in the following assemblies:
2+
// * pac/creating-pipeline-runs-pac.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="creating-pipeline-run-pac_{context}"]
6+
= Creating a pipeline run in {pac}
7+
8+
You can create a pipeline run definition for {pac} in your repository and match it to an event, such as a pull request. When the event happens, {pac} creates a `PipelineRun` custom resource (CR) from this definition, and then {pipelines-shortname} executes the pipeline run.
9+
10+
.Prerequisites
11+
12+
* You configured {pac} to integrate with your Git repository hosting service provider.
13+
14+
* You created a `Repository` custom resource (CR) to define the connection to your repository in {pac}.
15+
16+
* You have a `.tekton` directory in the root of your repository.
17+
18+
.Procedure
19+
20+
. Create a file with a `.yaml` or `.yml` extension in the `.tekton` directory.
21+
22+
. In the file that you created, create a YAML specification for a `PipelineRun` CR. This specification can use all features of {pipelines-shortname}.
23+
24+
. Depending on the requirements of your pipeline run definition, complete any of the following optional steps:
25+
26+
** Create other files with a `.yaml` or `.yml` extension in the `.tekton` directory. In these files, provide definitions of resources that your pipeline run definition references, such as `Pipeline`, `Task`, or `StepAction` CRs. The {pac} resolver automatically resolves these resources and includes them in the `PipelineRun` CR that is based on your definition.
27+
28+
** Use _dynamic variables_ in your pipeline run specification. {pac} replaces these variables with values that represent the current context. For example, `{{ repo_url }}` is the current URL for the repository and `{{ revision }}` is the commit SHA on which the pipeline run was started.
29+
+
30+
For more information about dynamic variables, see the "Dynamic variables in a pipeline run specification" section.
31+
32+
** Add one or more {pac} resolver annotations to your pipeline run definition. A {pac} resolver annotation references a pipeline or task in {tekton-hub}, an HTTP location, or a location in your repository outside the `.tekton` directory. If you create a {pac} resolver annotation to reference a resource, you can use this resource by name in your pipeline run definition. The {pac} resolver automatically resolves these resources and includes them in the `PipelineRun` CR that is based on your definition.
33+
+
34+
For more information about these annotations, see the "{pac} resolver annotations" section.
35+
36+
. Match the pipeline run to events by adding any of the following annotations to the pipeline run definition. When the defined event happens, {pac} starts the pipeline run. For more information about matching the pipeline run to events, see the "Annotations for matching events to a pipeline run" section.
37+
38+
** A combination of the `pipelinesascode.tekton.dev/on-event` annotation, which defines a `pull request` or `push` event, and a `pipelinesascode.tekton.dev/on-target-branch` annotation, which defines the branch that the pull request or push event must target. If you match your pipeline run to a pull request or push event, the pipeline run starts when the event is created. For pull requests, it starts again each time the source branch event is updated.
39+
+
40+
[NOTE]
41+
====
42+
If your Git repository provider uses merge requests and not pull requests, a `pull_request` event definition matches a merge request.
43+
====
44+
45+
** A `pipelinesascode.tekton.dev/on-comment` annotation, which matches the pipeline run to a comment on a pull request by regular expression. If you match your pipeline run to a comment, it starts when the comment is added to a pull request. To start the pipeline run again, add the comment again.
46+
47+
** A `pipelinesascode.tekton.dev/on-cel-expression` annotation, which matches the pipeline run if the specified Common Expression Language (CEL) expression evaluates to `true` on a pull request or push event.
48+
49+
. Optional: Add one or more annotations that filter the matching events. With these annotations, when the defined matching event (such as a pull request, a push event, or a comment) happens, {pac} checks if these annotations are also matched. The pipeline run starts only if all the annotations that you added to it are matched. For more information about filtering matching events, see the "Annotations for filtering events" section.
50+
51+
** A `pipelinesascode.tekton.dev/on-path-changed` annotation is matched if the pull request or push event affect files in the specified paths.
52+
53+
** A `pipelinesascode.tekton.dev/on-path-changed-ignore` annotation excludes matching the event if the event changes _only_ files in the specified paths and does not change any other files in the repository.
54+
55+
** A `pipelinesascode.tekton.dev/on-label` annotation is matched if the pull request or push event has one of the specified labels.
56+
57+
. Optional: Add the `pipelinesascode.tekton.dev/cancel-in-progress: "true"` annotation to enable automatic cancellation of the pipeline run in certain cases. 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 you enable automatic cancellation-in-progress, after a new copy of the pipeline run starts, {pac} cancels the older run to avoid running many copies of the pipeline run at the same time. For more information about this annotation, see the "Annotations for specifying automatic cancellation-in-progress for a pipeline run" section.
58+
59+
.Example {pac} pipeline run definition
60+
[source,yaml]
61+
----
62+
apiVersion: tekton.dev/v1
63+
kind: PipelineRun
64+
metadata:
65+
name: maven-build
66+
annotations:
67+
pipelinesascode.tekton.dev/task: "[git-clone]" # <1>
68+
pipelinesascode.tekton.dev/on-event: "[pull_request]" # <2>
69+
pipelinesascode.tekton.dev/on-target-branch: "[main, release]" # <3>
70+
pipelinesascode.tekton.dev/on-path-changed: "[src/**]" # <4>
71+
pipelinesascode.tekton.dev/cancel-in-progress: "true" # <5>
72+
spec:
73+
pipelineSpec:
74+
workspaces:
75+
- name: shared-workspace
76+
tasks:
77+
- name: fetch-repo
78+
taskRef:
79+
- name: git-clone # <6>
80+
params:
81+
- name: url
82+
value: {{ repo_url }} # <7>
83+
- name: revision
84+
value: {{ revision }} # <8>
85+
workspaces:
86+
- name: output
87+
workspace: shared-workspace
88+
- name: build-from-source
89+
taskRef:
90+
resolver: cluster
91+
params:
92+
- name: kind
93+
value: task
94+
- name: name
95+
value: maven
96+
- name: namespace
97+
value: openshift-pipelines
98+
workspaces:
99+
- name: source
100+
workspace: shared-workspace
101+
----
102+
<1> The `pipelinesascode.tekton.dev/task` annotation references the `git-clone` task from {tekton-hub}.
103+
<2> The `pipelinesascode.tekton.dev/on-event` annotation matches the pipeline run to a pull request or merge request event.
104+
<3> The `pipelinesascode.tekton.dev/on-target-branch` annotation specifies that a pull request into either the `main` branch or `release` branch triggers this pipeline run.
105+
<4> The `pipelinesascode.tekton.dev/on-path-changed` annotation specifies that the pipeline run triggers only if the pull request contains changes to files under the `src` directory.
106+
<5> The `pipelinesascode.tekton.dev/cancel-in-progress` annotation specifies that, if the pipeline run is started again for the same pull request, {pac} cancels the previous run.
107+
<6> The pipeline run specification references the `git-clone` task by name. Because of the `pipelinesascode.tekton.dev/task` annotation, the {pac} resolver resolves this reference to the `git-clone` task from {tekton-hub}.
108+
<7> {pac} replaces the `{{ repo_url }}` dynamic variable with the URL for the Git repository.
109+
<8> {pac} replaces the `{{ revision }}` dynamic variable with the revision of the branch for which the pipeline run was started.

‎modules/op-filtering-pipeline-run-using-pipelines-as-code.adoc

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
// This module is included in the following assemblies:
2+
// * pac/creating-pipeline-runs-pac.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="filtering-pipeline-run-using-pipelines-as-code_{context}"]
6+
= Annotations for filtering events matched to a pipeline run
7+
8+
You can add one or more annotations to a pipeline run to filter the events that are matched to this pipeline run. In this case, when the defined matching event (such as a pull request, a push event, or a comment) happens, {pac} checks if these annotations are also matched. The pipeline run starts only if all the annotations that you added to it are matched.
9+
10+
[id="path-matching-pipeline-run-using-pipelines-as-code_{context}"]
11+
== Matching changes in paths to a pipeline run
12+
13+
You can match a pipeline run to changes in a set of paths. {pac} starts the pipeline run only if the pull request or push event includes changes in any of the paths that you list.
14+
15+
The `pass:[*]` wildcard denotes any file in the directory. The `pass:[**]` wildcard denotes any file in the directory or any subdirectories on any level under the directory.
16+
17+
You can use the following example to match the `pipeline-pkg-or-cli` pipeline run when a pull request changes any files in the `pkg` directory, the `cli` directory, or any subdirectories under the `cli` directory.
18+
19+
[source,yaml]
20+
----
21+
apiVersion: tekton.dev/v1
22+
kind: PipelineRun
23+
metadata:
24+
name: pipeline-pkg-or-cli
25+
annotations:
26+
pipelinesascode.tekton.dev/on-path-changed: "[pkg/*, cli/**]"
27+
# ...
28+
----
29+
30+
[id="exclude-path-matching-pipeline-run-using-pipelines-as-code_{context}"]
31+
== Excluding changes in paths from matching a pipeline run
32+
33+
You can configure a pipeline run to exclude matching if a pull request makes changes only to files in a specified set of paths. If the pipeline run matches an event but the pull request includes changes only to files in the paths that you list, {pac} does not start the pipeline run.
34+
35+
You can use the following example to match the `pipeline-docs-not-generated` pipeline run when a pull request changes any files under the `docs` directory or its subdirectories, except when the changes apply only to the `docs/generated` directory or its subdirectories.
36+
37+
[source,yaml]
38+
----
39+
apiVersion: tekton.dev/v1
40+
kind: PipelineRun
41+
metadata:
42+
name: pipeline-docs-not-generated
43+
annotations:
44+
pipelinesascode.tekton.dev/on-path-changed: "[docs/**]"
45+
pipelinesascode.tekton.dev/on-path-changed-ignore: "[docs/generated/**]"
46+
# ...
47+
----
48+
49+
You can use the following example to match the `pipeline-main-not-docs` pipeline run when a pull request targets the `main` branch, except when the changes apply only to the `docs` directory or its subdirectories.
50+
51+
[source,yaml]
52+
----
53+
apiVersion: tekton.dev/v1
54+
kind: PipelineRun
55+
metadata:
56+
name: pipeline-main-not-docs
57+
annotations:
58+
pipelinesascode.tekton.dev/on-target-branch: "[main]"
59+
pipelinesascode.tekton.dev/on-event: "[pull_request]"
60+
pipelinesascode.tekton.dev/on-path-changed-ignore: "[docs/**]"
61+
# ...
62+
----
63+
64+
[id="label-matching-pipeline-run-using-pipelines-as-code_{context}"]
65+
== Matching a pull request label to a pipeline run
66+
67+
:FeatureName: Matching pull request labels to a pipeline run
68+
include::snippets/technology-preview.adoc[]
69+
70+
You can match a pipeline run to one or several pull request labels. {pac} starts the pipeline run only when the pull request has any of these labels. When the pull request is updated with a new commit, if the label is still present, {pac} starts the pipeline run again.
71+
72+
You can use the following example to match the `pipeline-bug-or-defect` pipeline run when either the `bug` label or the `defect` label is added to a pull request, and also when a pull request with this label is updated with a new commit:
73+
74+
[source,yaml]
75+
----
76+
apiVersion: tekton.dev/v1
77+
kind: PipelineRun
78+
metadata:
79+
name: pipeline-bug-or-defect
80+
annotations:
81+
pipelinesascode.tekton.dev/on-label: "[bug, defect]"
82+
# ...
83+
----
84+
85+
[NOTE]
86+
====
87+
The current version of {pac} supports matching events to pull request labels only for the GitHub, Gitea, and GitLab repository hosting service providers.
88+
====

‎modules/op-matching-pipeline-run-using-pipelines-as-code.adoc

Lines changed: 6 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
// This module is included in the following assemblies:
2-
// * pac/managing-pipeline-runs-pac.adoc
2+
// * pac/creating-pipeline-runs-pac.adoc
33

44
:_mod-docs-content-type: REFERENCE
55
[id="matching-pipeline-run-using-pipelines-as-code_{context}"]
@@ -50,89 +50,6 @@ annotations:
5050
* Tags such as `"refs/tags/1.\*"`
5151

5252

53-
[id="path-matching-pipeline-run-using-pipelines-as-code_{context}"]
54-
== Matching changes in paths to a pipeline run
55-
56-
You can match a pipeline run to changes in a set of paths. {pac} starts the pipeline run when a pull request includes changes in any of the paths that you list.
57-
58-
The `pass:[*]` wildcard denotes any file in the directory. The `pass:[**]` wildcard denotes any file in the directory or any subdirectories on any level under the directory.
59-
60-
You can use the following example to match the `pipeline-pkg-or-cli` pipeline run when a pull request changes any files in the `pkg` directory, the `cli` directory, or any subdirectories under the `cli` directory.
61-
62-
[source,yaml]
63-
----
64-
apiVersion: tekton.dev/v1
65-
kind: PipelineRun
66-
metadata:
67-
name: pipeline-pkg-or-cli
68-
annotations:
69-
pipelinesascode.tekton.dev/on-path-changed: "["pkg/*", "cli/**"]"
70-
# ...
71-
----
72-
73-
[id="exclude-path-matching-pipeline-run-using-pipelines-as-code_{context}"]
74-
== Excluding changes in paths from matching a pipeline run
75-
76-
You can configure a pipeline run to exclude matching if a pull request makes changes only to files in a specified set of paths. If the pipeline run matches an event but the pull request includes changes only to files in the paths that you list, {pac} does not start the pipeline run.
77-
78-
You can use the following example to match the `pipeline-docs-not-generated` pipeline run when a pull request changes any files under the `docs` directory or its subdirectories, except when the changes apply only to the `docs/generated` directory or its subdirectories.
79-
80-
[source,yaml]
81-
----
82-
apiVersion: tekton.dev/v1
83-
kind: PipelineRun
84-
metadata:
85-
name: pipeline-docs-not-generated
86-
annotations:
87-
pipelinesascode.tekton.dev/on-path-changed: "["docs/**"]"
88-
pipelinesascode.tekton.dev/on-path-changed-ignore: "["docs/generated/**"]"
89-
# ...
90-
----
91-
92-
You can use the following example to match the `pipeline-main-not-docs` pipeline run when a pull request targets the `main` branch, except when the changes apply only to the `docs` directory or its subdirectories.
93-
94-
[source,yaml]
95-
----
96-
apiVersion: tekton.dev/v1
97-
kind: PipelineRun
98-
metadata:
99-
name: pipeline-main-not-docs
100-
annotations:
101-
pipelinesascode.tekton.dev/on-target-branch: "[main]"
102-
pipelinesascode.tekton.dev/on-event: "[pull_request]"
103-
pipelinesascode.tekton.dev/on-path-changed-ignore: "["docs/**"]"
104-
# ...
105-
----
106-
107-
[id="label-matching-pipeline-run-using-pipelines-as-code_{context}"]
108-
== Matching a pull request label to a pipeline run
109-
110-
:FeatureName: Matching pull request labels to a pipeline run
111-
include::snippets/technology-preview.adoc[]
112-
113-
114-
// 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
115-
116-
You can match a pipeline run to one or several pull request labels. {pac} starts the pipeline run when any of these labels is added to a pull request. When the pull request is updated with a new commit, if the pull request still has the label, {pac} starts the pipeline run again.
117-
118-
You can use the following example to match the `pipeline-bug-or-defect` pipeline run when either the `bug` label or the `defect` label is added to a pull request, and also when a pull request with this label is updated with a new commit:
119-
120-
[source,yaml]
121-
----
122-
apiVersion: tekton.dev/v1
123-
kind: PipelineRun
124-
metadata:
125-
name: pipeline-bug-or-defect
126-
annotations:
127-
pipelinesascode.tekton.dev/on-label: "[bug, defect]"
128-
# ...
129-
----
130-
131-
[NOTE]
132-
====
133-
The current version of {pac} supports matching events to pull request labels only for the GitHub, Gitea, and GitLab repository hosting service providers.
134-
====
135-
13653
[id="comment-matching-pipeline-run-using-pipelines-as-code_{context}"]
13754
== Matching a comment event to a pipeline run
13855

@@ -164,6 +81,11 @@ The pipeline run starts only if the comment author meets one of the following re
16481

16582
{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.
16683

84+
[IMPORTANT]
85+
====
86+
If you use the `on-cel-expression` annotation in the same pipeline run as an `on-event`, `on-target-branch`, `on-label`, `on-path-change`, or `on-path-change-ignore` annotation, the `on-cel-expression` annotation takes priority and {pac} ignores the other annotations.
87+
====
88+
16789
To use CEL-based filtering with {pac}, consider the following examples of annotations:
16890

16991
* To match a `pull_request` event targeting the `main` branch and coming from the `wip` branch:

0 commit comments

Comments
 (0)