Skip to content

Commit 7e83517

Browse files
PreeticpPreeticp
authored
Merge pull request #43308 from sounix000/3752-pipeline-as-code
RHDEVDOCS-3752 Document Pipelines as code
2 parents 03c0a6b + f8434f6 commit 7e83517

10 files changed

+457
-0
lines changed

‎_attributes/common-attributes.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ endif::[]
8585
:pipelines-ver: pipelines-1.8
8686
:tekton-chains: Tekton Chains
8787
:tekton-hub: Tekton Hub
88+
:pac: Pipelines as Code
8889
//odo
8990
:odo-title: odo
9091
//alibaba cloud

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1628,6 +1628,8 @@ Topics:
16281628
File: managing-nonversioned-and-versioned-cluster-tasks
16291629
- Name: Using Tekton Hub with OpenShift Pipelines
16301630
File: using-tekton-hub-with-openshift-pipelines
1631+
- Name: Using Pipelines as Code
1632+
File: using-pipelines-as-code
16311633
- Name: Working with OpenShift Pipelines using the Developer perspective
16321634
File: working-with-pipelines-using-the-developer-perspective
16331635
- Name: Reducing resource consumption of OpenShift Pipelines

‎cicd/pipelines/creating-applications-with-cicd-pipelines.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ include::modules/op-enabling-monitoring-of-event-listeners-for-triggers-for-user
7676
[id="pipeline-addtl-resources"]
7777
== Additional resources
7878

79+
* To include pipelines as code along with with the application source code in the same repository, see xref:../../cicd/pipelines/using-pipelines-as-code.adoc#using-pipelines-as-code[Using Pipelines as code].
7980
* For more details on pipelines in the *Developer* perspective, see the xref:../../cicd/pipelines/working-with-pipelines-using-the-developer-perspective.adoc#working-with-pipelines-using-the-developer-perspective[working with pipelines in the *Developer* perspective] section.
8081
* To learn more about Security Context Constraints (SCCs), see the xref:../../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing Security Context Constraints] section.
8182
* For more examples of reusable tasks, see the link:https://github.com/openshift/pipelines-catalog[OpenShift Catalog] repository. Additionally, you can also see the Tekton Catalog in the Tekton project.

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
:_content-type: ASSEMBLY
2+
[id="using-pipelines-as-code"]
3+
= Using Pipelines as Code
4+
include::_attributes/common-attributes.adoc[]
5+
:context: using-pipelines-as-code
6+
7+
toc::[]
8+
9+
:FeatureName: Pipelines as Code
10+
include::snippets/technology-preview.adoc[]
11+
12+
[role="_abstract"]
13+
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.
14+
15+
[id="pac-key-features"]
16+
== Key features
17+
{pac} supports the following features:
18+
19+
* Pull request status and control on the platform hosting the Git repository.
20+
* GitHub Checks API to set the status of a pipeline run, including rechecks.
21+
* GitHub pull request and commit events.
22+
* Pull request actions in comments, such as `/retest`.
23+
* Git events filtering and a separate pipeline for each event.
24+
* Automatic task resolution in {pipelines-shortname}, including local tasks, Tekton Hub, and remote URLs.
25+
* Retrieval of configurations using GitHub blobs and objects API.
26+
* Access Control List (ACL) over a GitHub organization, or using a Prow style `OWNER` file.
27+
* The `tkn-pac` CLI plugin for managing bootstrapping and {pac} repositories.
28+
* Support for GitHub App, GitHub Webhook, Bitbucket Server, and Bitbucket Cloud.
29+
30+
include::modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc[leveloffset=+1]
31+
32+
include::modules/op-installing-pipelines-as-code-cli.adoc[leveloffset=+1]
33+
34+
include::modules/op-configuring-pipelines-as-code-for-a-git-repository-hosting-service-provider.adoc[leveloffset=+1]
35+
36+
include::modules/op-configuring-pipelines-as-code-for-a-github-app.adoc[leveloffset=+2]
37+
38+
include::modules/op-pipelines-as-code-command-reference.adoc[leveloffset=+1]
39+
40+
include::modules/op-customizing-pipelines-as-code-configuration.adoc[leveloffset=+1]
41+
42+
[role="_additional-resources"]
43+
[id="additional-resources-pac"]
44+
== Additional resources
45+
46+
* xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[Installing OpenShift Pipelines]
47+
48+
* xref:../../cli_reference/tkn_cli/installing-tkn.adoc#installing-tkn[Installing tkn]
49+
50+
* xref:../../cicd/pipelines/op-release-notes.adoc#op-release-notes[{pipelines-title} release notes]

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
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="configuring-pipelines-as-code-for-a-git-repository-hosting-service-provider_{context}"]
7+
= Configuring {pac} for a Git repository hosting service provider
8+
9+
[role="_abstract"]
10+
After installing {pac}, cluster administrators can configure a Git repository hosting service provider. Currently, the following services are supported:
11+
12+
* Github App
13+
* Github Webhook
14+
* Bitbucket Server
15+
* Bitbucket Cloud
16+
17+
[NOTE]
18+
====
19+
GitHub App is the recommended service for using Pipelines as Code.
20+
====
21+

‎modules/op-configuring-pipelines-as-code-for-a-github-app.adoc

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-pipelines-as-code.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="configuring-pipelines-as-code-for-a-github-app_{context}"]
7+
= Configuring {pac} for a GitHub App
8+
9+
[role="_abstract"]
10+
GitHub Apps act as a point of integration with {pipelines-title} and bring the advantage of Git-based workflows to OpenShift Pipelines. Cluster administrators can configure a single GitHub App for all cluster users. For GitHub Apps to work with Pipelines as Code, ensure that the webhook of the GitHub App points to the Pipelines as Code event listener route (or ingress endpoint) that listens for GitHub events.
11+
12+
[id="configuring-github-app-for-pac"]
13+
== Configuring a GitHub App
14+
15+
Cluster administrators can create a GitHub App by running the following command:
16+
17+
[source,terminal]
18+
----
19+
$ tkn pac bootstrap github-app
20+
----
21+
22+
If the `tkn pac` CLI plugin is not installed, you can create the GitHub App manually.
23+
24+
[discrete]
25+
.Procedure
26+
27+
To create and configure a GitHub App manually for {pac}, perform the following steps:
28+
29+
. Sign in to your GitHub account.
30+
31+
. Go to **Settings** --> **Developer settings** --> **GitHub Apps**, and click **New GitHub App**.
32+
33+
. Provide the following information in the GitHub App form:
34+
35+
* **GitHub Application Name**: `OpenShift Pipelines`
36+
* **Homepage URL**: OpenShift Console URL
37+
* **Webhook URL**: The {pac} route or ingress URL. You can find it by executing the command `echo https://$(oc get route -n pipelines-as-code el-pipelines-as-code-interceptor -o jsonpath='{.spec.host}')`.
38+
+
39+
[NOTE]
40+
====
41+
For {pac} installated by default using the {pipelines-title} Operator, use the `openshift-pipelines` namespace instead of `pipelines-as-code`.
42+
====
43+
+
44+
* **Webhook secret**: An arbitrary secret. You can generate a secret by executing the command `openssl rand -hex 20`.
45+
46+
. Select the following **Repository permissions**:
47+
48+
* **Checks**: `Read & Write`
49+
* **Contents**: `Read & Write`
50+
* **Issues**: `Read & Write`
51+
* **Metadata**: `Read-only`
52+
* **Pull request**: `Read & Write`
53+
54+
. Select the following **Organization permissions**:
55+
56+
* **Members**: `Readonly`
57+
* **Plan**: `Readonly`
58+
59+
. Select the following **User permissions**:
60+
61+
* **Commit comment**
62+
* **Issue comment**
63+
* **Pull request**
64+
* **Pull request review**
65+
* **Pull request review comment**
66+
* **Push**
67+
68+
. Click **Create GitHub App**.
69+
70+
. On the **Details** page of the newly created GitHub App, note the **App ID** displayed at the top.
71+
72+
. In the **Private keys** section, click **Generate Private key** to automatically generate and download a private key for the GitHub app. Securely store the private key for future reference and usage.
73+
74+
75+
[id="configuring-pac-for-github-app"]
76+
== Configuring {pac} to access a GitHub App
77+
78+
To configure {pac} to access the newly created GitHub App, execute the following command:
79+
+
80+
[source,terminal]
81+
----
82+
$ oc -n <pipelines-as-code> create secret generic pipelines-as-code-secret \ <1>
83+
--from-literal github-private-key="$(cat <PATH_PRIVATE_KEY>)" \ <2>
84+
--from-literal github-application-id="<APP_ID>" \ <3>
85+
--from-literal webhook.secret="<WEBHOOK_SECRET>" <4>
86+
----
87+
<1> For {pac} installated by default using the {pipelines-title} Operator, use the `openshift-pipelines` namespace instead of `pipelines-as-code`.
88+
<2> The path to the private key you downloaded while configuring the GitHub App.
89+
<3> The **App ID** of the GitHub App.
90+
<4> The webhook secret provided when you created the GitHub App.
91+
92+
93+
[NOTE]
94+
====
95+
{pac} works automatically with GitHub Enterprise by detecting the header set from GitHub Enterprise and using it for the GitHub Enterprise API authorization URL.
96+
====
97+

‎modules/op-customizing-pipelines-as-code-configuration.adoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
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="customizing-pipelines-as-code-configuration_{context}"]
7+
= Customizing {pac} configuration
8+
9+
[role="_abstract"]
10+
To customize {pac}, cluster administrators can configure the following parameters using the `pipelines-as-code` config map in the `pipelines-as-code` namespace:
11+
12+
.Customizing {pac} configuration
13+
[options="header"]
14+
|===
15+
16+
| Parameter | Description | Default
17+
18+
| `application-name` | The name of the application. For example, the name displayed in the GitHub Checks labels. | `"Pipelines as Code CI"`
19+
20+
| `max-keep-days` | The number of the days for which the executed pipeline runs are kept in the `pipelines-as-code namespace`.
21+
22+
Note that this configmap setting does not affect the cleanups of a user's pipeline runs, which are controlled by the annotations on the pipeline run definition in the user's GitHub repository. |
23+
24+
| `secret-auto-create` | Indicates whether or not a secret should be automatically created using the token generated in the GitHub application. This secret can then be used with private repositories. | `enabled`
25+
26+
| `remote-tasks` | When enabled, allows remote tasks from pipeline run annotations. | `enabled`
27+
28+
| `hub-url` | The base URL for the link:https://api.hub.tekton.dev/v1[Tekton Hub API]. | `https://hub.tekton.dev/`
29+
30+
|===

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-pipelines-as-code.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="installing-pipelines-as-code-cli_{context}"]
7+
= Installing {pac} CLI
8+
9+
[role="_abstract"]
10+
Cluster administrators can use the `tkn-pac` CLI tool on local machines or as containers for testing. The `tkn-pac` CLI tool is installed automatically when you install the `tkn` CLI for {pipelines-title}.
11+
12+
You can also install the `tkn-pac` `tkn-pac` version `0.23.1` binaries for the supported platforms:
13+
14+
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.23.1/tkn-pac-linux-amd64-0.23.1.tar.gz[Linux (x86_64, amd64)]
15+
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.23.1/tkn-pac-linux-s390x-0.23.1.tar.gz[Linux on IBM Z and LinuxONE (s390x)]
16+
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.23.1/tkn-pac-linux-ppc64le-0.23.1.tar.gz[Linux on IBM Power Systems (ppc64le)]
17+
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.23.1/tkn-pac-macos-amd64-0.23.1.tar.gz[Mac]
18+
* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.23.1/tkn-pac-windows-amd64-0.23.1.zip[Windows]
19+
+
20+
[NOTE]
21+
====
22+
The binaries are compatible with `tkn` version `0.23.1`.
23+
====
24+
25+
In addition, you can install `tkn-pac` using the following methods:
26+
27+
[CAUTION]
28+
====
29+
The `tkn-pac` CLI tool available using these methods is _not updated regularly_.
30+
====
31+
32+
* Install on Linux or Mac OS using the `brew` package manager:
33+
+
34+
[source,terminal]
35+
----
36+
$ brew install openshift-pipelines/pipelines-as-code/tektoncd-pac
37+
----
38+
+
39+
You can upgrade the package by running the following command:
40+
+
41+
[source,terminal]
42+
----
43+
$ brew upgrade openshift-pipelines/pipelines-as-code/tektoncd-pac
44+
----
45+
46+
* Install as a container using `podman`:
47+
+
48+
[source,terminal]
49+
----
50+
$ podman run -e KUBECONFIG=/tmp/kube/config -v ${HOME}/.kube:/tmp/kube \
51+
-it quay.io/openshift-pipeline/pipelines-as-code tkn-pac help
52+
----
53+
+
54+
You can also use `docker` as a substitute for `podman`.
55+
56+
* Install from the GitHub repository using `go`:
57+
+
58+
[source,terminal]
59+
----
60+
$ go install github.com/openshift-pipelines/pipelines-as-code/cmd/tkn-pac
61+
----

‎modules/op-installing-pipelines-as-code-on-an-openshift-cluster.adoc

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-pipelines-as-code.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="installing-pipelines-as-code-on-an-openshift-cluster_{context}"]
7+
= Installing {pac} on an {product-title}
8+
9+
[role="_abstract"]
10+
{pac} is installed by default when you install the {pipelines-title} Operator. If you are using {pipelines-shortname} 1.7 or later versions, skip the procedure for manual installation of {pac}.
11+
12+
However, if you want to disable the default installation of {pac} with the {pipelines-title} Operator, set the value of the `enablePipelinesAsCode` field as `false` in the `TektonConfig` custom resource.
13+
14+
[source,yaml]
15+
----
16+
...
17+
spec:
18+
addon:
19+
enablePipelinesAsCode: false
20+
...
21+
----
22+
23+
To install {pac} using the Operator, set the value of the `enablePipelinesAsCode` field to `true`.
24+
25+
[discrete]
26+
.Procedure
27+
28+
. To _manually_ install {pac} on a {product-title} cluster instead of the default installation with the {pipelines-title} Operator, run the following command:
29+
+
30+
[source,terminal]
31+
----
32+
$ VERSION=0.5.4
33+
$ oc apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/release-$VERSION/release-$VERSION.yaml
34+
----
35+
+
36+
[NOTE]
37+
====
38+
For the latest stable version, check the link:https://github.com/openshift-pipelines/pipelines-as-code/releases[release page]. In addition, check the {pipelines-title} release notes to ensure that the {pac} version is compatible with the {pipelines-title} version.
39+
====
40+
+
41+
This command installs {pac} in the `pipelines-as-code` namespace and creates user roles and the route URL for the {pac} event listener.
42+
43+
. Note the route URL for the {pac} controller created on the cluster:
44+
+
45+
[source,terminal]
46+
----
47+
$ echo https://$(oc get route -n pipelines-as-code el-pipelines-as-code-interceptor -o jsonpath='{.spec.host}')
48+
----
49+
+
50+
This URL will be needed later when you configure the Git repository hosting service provider.
51+
52+
. (Optional) To allow non-administrative users to create repository custom resource definitions (CRDs) in their respective namespaces, create a `RoleBinding` object with the name `openshift-pipeline-as-code-clusterrole` in the namespace. For example, to allow a user to create a repository CRD in the `user-ci` namespace, run the following command:
53+
+
54+
[source,terminal]
55+
----
56+
$ oc adm policy add-role-to-user openshift-pipeline-as-code-clusterrole user -n user-ci
57+
----
58+
+
59+
Alternatively, apply the following YAML file using the `oc apply -f <RoleBinding.yaml>` command:
60+
+
61+
[source,yaml]
62+
----
63+
apiVersion: rbac.authorization.k8s.io/v1
64+
kind: RoleBinding
65+
metadata:
66+
name: openshift-pipeline-as-code-clusterrole
67+
namespace: user-ci
68+
roleRef:
69+
apiGroup: rbac.authorization.k8s.io
70+
kind: ClusterRole
71+
name: openshift-pipeline-as-code-clusterrole
72+
subjects:
73+
- apiGroup: rbac.authorization.k8s.io
74+
kind: User
75+
name: user
76+
----

0 commit comments

Comments
 (0)