Skip to content

Commit 330bf70

Browse files
author
Souvik Sarkar
committed
Pipelines as Code documentation for Pipelines 1.9
updates updates trying to correct build errors trying to correct build errors trying to fix build errors structure intermediate draft complete github webhook gitlab bitbucket all repo crd and concurrency limits revisions all about resolvers creating pipeline runs pac minor fixes private repo pipeline run clean ups incoming webhooks running pipelines status correcting build error SME and QE comments editorial changes editorial
1 parent ffa3ddd commit 330bf70

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)