Skip to content

Commit a8daa2f

Browse files
rolfedhrolfedh
authored
Merge pull request #53813 from sounix000/pac-for-1-9
Pipelines as Code documentation for Pipelines 1.9
2 parents a85dfe3 + 330bf70 commit a8daa2f

22 files changed

+1533
-49
lines changed

‎_attributes/common-attributes.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ endif::[]
8888
//pipelines
8989
:pipelines-title: Red Hat OpenShift Pipelines
9090
:pipelines-shortname: Pipelines
91-
:pipelines-ver: pipelines-1.8
91+
:pipelines-ver: pipelines-1.9
9292
:tekton-chains: Tekton Chains
9393
:tekton-hub: Tekton Hub
9494
:pac: Pipelines as Code

‎cicd/pipelines/using-pipelines-as-code.adoc

Lines changed: 91 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9-
:FeatureName: Pipelines as Code
9+
// :FeatureName: Pipelines as Code
1010

1111
[role="_abstract"]
1212
With {pac}, cluster administrators and users with the required privileges can define pipeline templates as part of source code Git repositories. When triggered by a source code push or a pull request for the configured Git repository, the feature runs the pipeline and reports the status.
@@ -30,20 +30,107 @@ include::modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc[le
3030

3131
include::modules/op-installing-pipelines-as-code-cli.adoc[leveloffset=+1]
3232

33-
include::modules/op-configuring-pipelines-as-code-for-a-git-repository-hosting-service-provider.adoc[leveloffset=+1]
33+
[id="using-pipelines-as-code-with-a-git-repository-hosting-service-provider"]
34+
== Using {pac} with a Git repository hosting service provider
3435

35-
include::modules/op-configuring-pipelines-as-code-for-a-github-app.adoc[leveloffset=+2]
36+
[role="_abstract"]
37+
After installing {pac}, cluster administrators can configure a Git repository hosting service provider. Currently, the following services are supported:
38+
39+
* GitHub App
40+
* GitHub Webhook
41+
* GitLab
42+
* Bitbucket Server
43+
* Bitbucket Cloud
44+
45+
[NOTE]
46+
====
47+
GitHub App is the recommended service for using with {pac}.
48+
====
49+
50+
include::modules/op-using-pipelines-as-code-with-a-github-app.adoc[leveloffset=+1]
3651

3752
include::modules/op-creating-a-github-application-in-administrator-perspective.adoc[leveloffset=+2]
3853

39-
include::modules/op-pipelines-as-code-command-reference.adoc[leveloffset=+1]
54+
include::modules/op-using-pipelines-as-code-with-github-webhook.adoc[leveloffset=+1]
55+
56+
.Additional resources
57+
58+
* link:https://docs.github.com/en/developers/webhooks-and-events/webhooks/creating-webhooks[GitHub Webhook documentation on GitHub]
59+
* link:https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api[GitHub Check Runs documentation on GitHub]
60+
* link:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token[Creating a personal access token on GitHub]
61+
* link:https://github.com/settings/tokens/new?description=pipelines-as-code-token&scopes=repo[Classic tokens with pre-filled permissions]
62+
63+
include::modules/op-using-pipelines-as-code-with-gitlab.adoc[leveloffset=+1]
64+
65+
.Additional resources
66+
67+
* link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html[GitLab Webhook documentation on GitLab]
68+
69+
include::modules/op-using-pipelines-as-code-with-bitbucket-cloud.adoc[leveloffset=+1]
70+
71+
.Additional resources
72+
73+
* link:https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/[Create app password on Bitbucket Cloud]
74+
* link:https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#introducing-atlassian-account-id-and-nicknames[Introducing Altassian Account ID and Nicknames]
75+
76+
include::modules/op-using-pipelines-as-code-with-bitbucket-server.adoc[leveloffset=+1]
77+
78+
.Additional resources
79+
80+
* link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Create personal tokens on Bitbucket Server]
81+
* link:https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/#Create-webhooks[Create webhooks on Bitbucket server]
82+
83+
include::modules/op-interfacing-pipelines-as-code-with-custom-certificates.adoc[leveloffset=+1]
84+
85+
.Additional resources
86+
87+
* xref:../../networking/enable-cluster-wide-proxy.adoc#nw-proxy-configure-object[Enabling the cluster-wide proxy]
88+
89+
include::modules/op-using-repository-crd-with-pipelines-as-code.adoc[leveloffset=+1]
90+
91+
include::modules/op-setting-concurrency-limits-in-repository-crd.adoc[leveloffset=+2]
92+
93+
include::modules/op-using-pipelines-as-code-resolver.adoc[leveloffset=+1]
94+
95+
include::modules/op-using-remote-task-annotations-with-pipelines-as-code.adoc[leveloffset=+2]
96+
97+
include::modules/op-using-remote-pipeline-annotations-with-pipelines-as-code.adoc[leveloffset=+2]
98+
99+
include::modules/op-creating-pipeline-run-using-pipelines-as-code.adoc[leveloffset=+1]
100+
101+
.Additional resources
102+
103+
* link:https://github.com/google/cel-spec/blob/master/doc/langdef.md[CEL language specification]
104+
105+
include::modules/op-running-pipeline-run-using-pipelines-as-code.adoc[leveloffset=+1]
106+
107+
include::modules/op-monitoring-pipeline-run-status-using-pipelines-as-code.adoc[leveloffset=+1]
108+
109+
.Additional resources
110+
111+
* link:https://github.com/chmouel/tekton-slack-task-status[An example task to send Slack messages on success or failure]
112+
* link:https://github.com/openshift-pipelines/pipelines-as-code/blob/7b41cc3f769af40a84b7ead41c6f037637e95070/.tekton/push.yaml[An example of a pipeline run with `finally` tasks triggered on push events]
113+
114+
include::modules/op-using-private-repositories-with-pipelines-as-code.adoc[leveloffset=+1]
115+
116+
.Additional resources
117+
118+
* link:https://github.com/openshift-pipelines/pipelines-as-code/blob/main/test/testdata/pipelinerun_git_clone_private.yaml[An example of the `git-clone` task used for cloning private repositories]
119+
120+
include::modules/op-cleaning-up-pipeline-run-using-pipelines-as-code.adoc[leveloffset=+1]
121+
122+
include::modules/op-using-incoming-webhook-with-pipelines-as-code.adoc[leveloffset=+1]
40123

41124
include::modules/op-customizing-pipelines-as-code-configuration.adoc[leveloffset=+1]
42125

126+
include::modules/op-pipelines-as-code-command-reference.adoc[leveloffset=+1]
127+
43128
[role="_additional-resources"]
44129
[id="additional-resources-pac"]
45130
== Additional resources
46131

132+
* link:https://github.com/openshift-pipelines/pipelines-as-code/tree/main/.tekton[An example of the `.tekton/` directory in the Pipelines as Code repository]
133+
47134
* xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[Installing OpenShift Pipelines]
48135

49136
* xref:../../cli_reference/tkn_cli/installing-tkn.adoc#installing-tkn[Installing tkn]

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-pipelines-as-code.adoc
4+
5+
:_content-type: REFERENCE
6+
[id="cleaning-up-pipeline-run-using-pipelines-as-code_{context}"]
7+
= Cleaning up pipeline run using {pac}
8+
9+
[role="_abstract"]
10+
11+
There can be many pipeline runs in a user namespace. By setting the `max-keep-runs` annotation, you can configure {pac} to retain a limited number of pipeline runs that matches an event. For example:
12+
13+
[source,yaml]
14+
----
15+
...
16+
pipelinesascode.tekton.dev/max-keep-runs: "<max_number>" <1>
17+
...
18+
----
19+
<1> {pac} starts cleaning up right after it finishes a successful execution, retaining only the maximum number of pipeline runs configured using the annotation.
20+
+
21+
[NOTE]
22+
====
23+
* {pac} skips cleaning the running pipelines, but cleans up the pipeline runs with an unknown status.
24+
* {pac} skips cleaning a failed pull request.
25+
====
26+

‎modules/op-configuring-pipelines-as-code-for-a-git-repository-hosting-service-provider.adoc

Lines changed: 0 additions & 22 deletions
This file was deleted.

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-pipelines-as-code.adoc
4+
5+
:_content-type: REFERENCE
6+
[id="creating-pipeline-run-using-pipelines-as-code_{context}"]
7+
= Creating a pipeline run using {pac}
8+
9+
[role="_abstract"]
10+
To run pipelines using {pac}, you can create pipelines 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.
11+
12+
The {pac} resolver bundles the pipeline runs with all tasks as a single pipeline run without any external dependencies.
13+
14+
[NOTE]
15+
====
16+
* For pipelines, use at least one pipeline run with a spec, or a separated `Pipeline` object.
17+
* For tasks, embed task spec inside a pipeline, or define separately as a Task object.
18+
====
19+
20+
[discrete]
21+
.Parameterizing commits and URLs
22+
23+
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:
24+
25+
* `{{repo_owner}}`: The repository owner.
26+
* `{{repo_name}}`: The repository name.
27+
* `{{repo_url}}`: The repository full URL.
28+
* `{{revision}}`: Full SHA revision of a commit.
29+
* `{{sender}}`: The username or account id of the sender of the commit.
30+
* `{{source_branch}}`: The branch name where the event originated.
31+
* `{{target_branch}}`: The branch name that the event targets. For push events, it's the same as the `source_branch`.
32+
* `{{pull_request_number}}`: The pull or merge request number, defined only for a `pull_request` event type.
33+
* `{{git_auth_secret}}`: The secret name that is generated automatically with Git provider's token for checking out private repos.
34+
35+
[discrete]
36+
.Matching an event to a pipeline run
37+
38+
You can match different Git provider events with each pipeline 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.
39+
40+
[discrete]
41+
.Matching a pull event to a pipeline run
42+
43+
You can use the following example to match the `pipeline-pr-main` pipeline with a `pull_request` event that targets the `main` branch:
44+
45+
[source,yaml]
46+
----
47+
...
48+
metadata:
49+
name: pipeline-pr-main
50+
annotations:
51+
pipelinesascode.tekton.dev/on-target-branch: "[main]" <1>
52+
pipelinesascode.tekton.dev/on-event: "[pull_request]"
53+
...
54+
----
55+
<1> You can specifiy multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following:
56+
* Full references to branches such as `"refs/heads/main"`
57+
* Globs with pattern matching such as `"refs/heads/\*"`,
58+
* Tags such as `"refs/tags/1.\*"`.
59+
60+
[discrete]
61+
.Matching a push event to a pipeline run
62+
63+
You can use the following example to match the `pipeline-push-on-main` pipeline with a `push` event targeting the `refs/heads/main` branch:
64+
65+
[source,yaml]
66+
----
67+
...
68+
metadata:
69+
name: pipeline-push-on-main
70+
annotations:
71+
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" <1>
72+
pipelinesascode.tekton.dev/on-event: "[push]"
73+
...
74+
----
75+
<1> You can specifiy multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following:
76+
* Full references to branches such as `"refs/heads/main"`
77+
* Globs with pattern matching such as `"refs/heads/\*"`,
78+
* Tags such as `"refs/tags/1.\*"`.
79+
80+
[discrete]
81+
.Advanced event matching
82+
83+
{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 allows complex filtering and negation.
84+
85+
To use CEL based filtering with {pac}, consider the following examples of annotations:
86+
87+
* To match a `pull_request` event targeting the `main` branch and coming from the `wip` branch:
88+
+
89+
[source,yaml]
90+
----
91+
...
92+
pipelinesascode.tekton.dev/on-cel-expression: |
93+
event == "pull_request" && target_branch == "main" && source_branch == "wip"
94+
...
95+
----
96+
97+
* To run a pipeline only if a path has changed, you can use the `.pathChanged` suffix function with a glob pattern:
98+
+
99+
[source,yaml]
100+
----
101+
...
102+
pipelinesascode.tekton.dev/on-cel-expression: |
103+
event == "pull_request" && "docs/\*.md".pathChanged() <1>
104+
...
105+
----
106+
<1> Matches all markdown files in the `docs` directory.
107+
108+
* To match all pull requests starting with the title `[DOWNSTREAM]`:
109+
+
110+
[source,yaml]
111+
----
112+
...
113+
pipelinesascode.tekton.dev/on-cel-expression: |
114+
event == "pull_request && event_title.startsWith("[DOWNSTREAM]")
115+
...
116+
----
117+
118+
* To run a pipeline on a `pull_request` event, but skipping the `experimental` branch:
119+
+
120+
[source,yaml]
121+
----
122+
...
123+
pipelinesascode.tekton.dev/on-cel-expression: |
124+
event == "pull_request" && target_branch != experimental"
125+
...
126+
----
127+
128+
For advanced CEL based filtering while using {pac}, you can use the following fields and suffix functions:
129+
130+
* `event`: A `push` or `pull_request` event.
131+
* `target_branch`: The target branch.
132+
* `source_branch`: The branch of origin of a `pull_request` event. For `push` events, it is same as the `target_branch`.
133+
* `event_title`: Matches the title of the event, such as the commit title for a `push` event, and the title of a pull or merge request for a `pull_request` event. Currently, only GitHub, Gitlab, and BitbucketCloud are the supported providers.
134+
* `.pathChanged`: A suffix function to a string. The string can be a glob of a path to check if the path has changed. Currently, only GitHub and Gitlab are supported as providers.
135+
136+
[discrete]
137+
.Using the temporary Github App token for Github API operations
138+
139+
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 as generated for private repositories in the `git-provider-token` key.
140+
141+
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:
142+
143+
[source,yaml]
144+
----
145+
...
146+
pipelinesascode.tekton.dev/task: "github-add-comment"
147+
...
148+
----
149+
150+
You can then add a task to the `tasks` section or `finally` tasks in the pipeline run definition:
151+
152+
[source,yaml]
153+
----
154+
[...]
155+
tasks:
156+
- name:
157+
taskRef:
158+
name: github-add-comment
159+
params:
160+
- name: REQUEST_URL
161+
value: "{{ repo_url }}/pull/{{ pull_request_number }}" <1>
162+
- name: COMMENT_OR_FILE
163+
value: "Pipelines as Code IS GREAT!"
164+
- name: GITHUB_TOKEN_SECRET_NAME
165+
value: "{{ git_auth_secret }}"
166+
- name: GITHUB_TOKEN_SECRET_KEY
167+
value: "git-provider-token"
168+
...
169+
----
170+
<1> By using the dynamic variables, you can reuse this snippet template for any pull request from any repository.
171+
172+
[NOTE]
173+
====
174+
On GitHub apps, the generated installation token is available for 8 hours, and scoped to the repository from here the events originate, unless configured differently on the cluster.
175+
====
176+

‎modules/op-installing-pipelines-as-code-cli.adoc

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,21 @@
77
= Installing {pac} CLI
88

99
[role="_abstract"]
10-
Cluster administrators can use the `tkn-pac` and `opc` CLI tools on local machines or as containers for testing. The `tkn-pac` and `opc` CLI tools are installed automatically when you install the `tkn` CLI for {pipelines-title}.
10+
Cluster administrators can use the `tkn pac` and `opc` CLI tools on local machines or as containers for testing. The `tkn pac` and `opc` CLI tools are installed automatically when you install the `tkn` CLI for {pipelines-title}.
1111

12-
You can install the `tkn-pac` and `opc` version `1.9.1` binaries for the supported platforms:
12+
You can install the `tkn pac` and `opc` version `1.9.1` binaries for the supported platforms:
1313

1414
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/1.9.1/tkn-linux-amd64.tar.gz[Linux (x86_64, amd64)]
1515
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/1.9.1/tkn-linux-s390x.tar.gz[Linux on {ibmzProductName} and {linuxoneProductName} (s390x)]
1616
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/1.9.1/tkn-linux-ppc64le.tar.gz[Linux on {ibmpowerProductName} (ppc64le)]
1717
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/1.9.1/tkn-macos-amd64.tar.gz[macOS]
1818
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/1.9.1/tkn-windows-amd64.zip[Windows]
1919
20-
// In addition, you can install `tkn-pac` using the following methods:
20+
// In addition, you can install `tkn pac` using the following methods:
2121

2222
// [CAUTION]
2323
// ====
24-
// The `tkn-pac` CLI tool available using these methods is _not updated regularly_.
24+
// The `tkn pac` CLI tool available using these methods is _not updated regularly_.
2525
// ====
2626

2727
// * Install on Linux or Mac OS using the `brew` package manager:
@@ -43,7 +43,7 @@ You can install the `tkn-pac` and `opc` version `1.9.1` binaries for the support
4343
// [source,terminal]
4444
// ----
4545
// $ podman run -e KUBECONFIG=/tmp/kube/config -v ${HOME}/.kube:/tmp/kube \
46-
// -it quay.io/openshift-pipeline/pipelines-as-code tkn-pac help
46+
// -it quay.io/openshift-pipeline/pipelines-as-code tkn pac help
4747
// ----
4848
// +
4949
// You can also use `docker` as a substitute for `podman`.

0 commit comments

Comments
 (0)