Skip to content

Commit 04e2fc3

Browse files
shipsingshipsing
committed
RHDEVDOCS-5061: Documenting pull request capabilities in GitHub Interceptor
1 parent cb34699 commit 04e2fc3

4 files changed

+202
-0
lines changed

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,12 @@ include::modules/op-enabling-monitoring-of-event-listeners-for-triggers-for-user
7070

7171
* xref:../../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects]
7272

73+
include::modules/op-configuring-pull-request-capabilities-in-GitHub-interceptor.adoc[leveloffset=+1]
74+
75+
include::modules/op-filtering-pull-requests-using-GitHub-interceptor.adoc[leveloffset=+2]
76+
77+
include::modules/op-validating-pull-requests-using-GitHub-interceptors.adoc[leveloffset=+2]
78+
7379
[role="_additional-resources"]
7480
[id="pipeline-addtl-resources"]
7581
== Additional resources

‎modules/op-configuring-pull-request-capabilities-in-GitHub-interceptor.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Ths module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/creating-applications-with-cicd-pipelines.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="op-configuring-pull-request-capabilities-in-GitHub-interceptor_{context}"]
7+
= Configuring pull request capabilities in GitHub Interceptor
8+
9+
With GitHub Interceptor, you can create logic that validates and filters GitHub webhooks. For example, you can validate the webhook’s origin and filter incoming events based on specified criteria. When you use GitHub Interceptor to filter event data, you can specify the event types that Interceptor can accept in a field.
10+
In {pipelines-title}, you can use the following capabilities of GitHub Interceptor:
11+
12+
* Filter pull request events based on the files that have been changed
13+
* Validate pull requests based on configured GitHub owners

‎modules/op-filtering-pull-requests-using-GitHub-interceptor.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 assembly:
2+
//
3+
// *cicd/pipelines/creating-applications-with-cicd-pipelines.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="op-filtering-pull-requests-using-GitHub-interceptor_{context}"]
7+
= Filtering pull requests using GitHub Interceptor
8+
9+
You can filter GitHub events based on the files that have been changed for push and pull events. This helps you to execute a pipeline for only relevant changes in your Git repository.
10+
GitHub Interceptor adds a comma delimited list of all files that have been changed and uses the CEL Interceptor to filter incoming events based on the changed files. The list of changed files is added to the `changed_files` property of the event payload in the top-level `extensions` field.
11+
12+
.Prerequistes
13+
* You have installed the {pipelines-title} Operator.
14+
15+
.Procedure
16+
. Perform one of the following steps:
17+
* For a public GitHub repository, set the value of the `addChangedFiles` parameter to `true` in the YAML configuration file shown below:
18+
+
19+
[source,yaml]
20+
----
21+
apiVersion: triggers.tekton.dev/v1beta1
22+
kind: EventListener
23+
metadata:
24+
name: github-add-changed-files-pr-listener
25+
spec:
26+
triggers:
27+
- name: github-listener
28+
interceptors:
29+
- ref:
30+
name: "github"
31+
kind: ClusterInterceptor
32+
apiVersion: triggers.tekton.dev
33+
params:
34+
- name: "secretRef"
35+
value:
36+
secretName: github-secret
37+
secretKey: secretToken
38+
- name: "eventTypes"
39+
value: ["pull_request", "push"]
40+
- name: "addChangedFiles"
41+
value:
42+
enabled: true
43+
- ref:
44+
name: cel
45+
params:
46+
- name: filter
47+
value: extensions.changed_files.matches('controllers/')
48+
...
49+
----
50+
51+
* For a private GitHub repository, set the value of the `addChangedFiles` parameter to `true` and provide the access token details, `secretName` and `secretKey` in the YAML configuration file shown below:
52+
+
53+
[source,yaml]
54+
----
55+
apiVersion: triggers.tekton.dev/v1beta1
56+
kind: EventListener
57+
metadata:
58+
name: github-add-changed-files-pr-listener
59+
spec:
60+
triggers:
61+
- name: github-listener
62+
interceptors:
63+
- ref:
64+
name: "github"
65+
kind: ClusterInterceptor
66+
apiVersion: triggers.tekton.dev
67+
params:
68+
- name: "secretRef"
69+
value:
70+
secretName: github-secret
71+
secretKey: secretToken
72+
- name: "eventTypes"
73+
value: ["pull_request", "push"]
74+
- name: "addChangedFiles"
75+
value:
76+
enabled: true
77+
personalAccessToken:
78+
secretName: github-pat
79+
secretKey: token
80+
- ref:
81+
name: cel
82+
params:
83+
- name: filter
84+
value: extensions.changed_files.matches('controllers/')
85+
...
86+
----
87+
88+
. Save the configuration file.

‎modules/op-validating-pull-requests-using-GitHub-interceptors.adoc

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/creating-applications-with-cicd-pipelines.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="op-validating-pull-requests-using-GitHub-interceptors_{context}"]
7+
= Validating pull requests using GitHub Interceptors
8+
9+
You can use GitHub Interceptor to validate the processing of pull requests based on the GitHub owners configured for a repository. This validation helps you to prevent unnecessary execution of a `PipelineRun` or `TaskRun` object.
10+
GitHub Interceptor processes a pull request only if the user name is listed as an owner or if a configurable comment is issued by an owner of the repository. For example, when you comment `/ok-to-test` on a pull request as an owner, a `PipelineRun` or `TaskRun` is triggered.
11+
12+
[NOTE]
13+
====
14+
Owners are configured in an `OWNERS` file at the root of the repository.
15+
====
16+
17+
.Prerequisites
18+
* You have installed the {pipelines-title} Operator.
19+
20+
.Procedure
21+
. Create a secret string value.
22+
. Configure the GitHub webhook with that value.
23+
. Create a Kubernetes secret named `secretRef` that contains your secret value.
24+
. Pass the Kubernetes secret as a reference to your GitHub Interceptor.
25+
. Create an `owners` file and add the list of approvers into the `approvers` section.
26+
. Perform one of the following steps:
27+
* For a public GitHub repository, set the value of the `githubOwners` parameter to `true` in the YAML configuration file shown below:
28+
+
29+
[source,yaml]
30+
----
31+
apiVersion: triggers.tekton.dev/v1beta1
32+
kind: EventListener
33+
metadata:
34+
name: github-owners-listener
35+
spec:
36+
triggers:
37+
- name: github-listener
38+
interceptors:
39+
- ref:
40+
name: "github"
41+
kind: ClusterInterceptor
42+
apiVersion: triggers.tekton.dev
43+
params:
44+
- name: "secretRef"
45+
value:
46+
secretName: github-secret
47+
secretKey: secretToken
48+
- name: "eventTypes"
49+
value: ["pull_request", "issue_comment"]
50+
- name: "githubOwners"
51+
value:
52+
enabled: true
53+
checkType: none
54+
...
55+
----
56+
57+
* For a private GitHub repository, set the value of the `githubOwners` parameter to `true` and provide the access token details, `secretName` and `secretKey` in the YAML configuration file shown below:
58+
+
59+
[source,yaml]
60+
----
61+
apiVersion: triggers.tekton.dev/v1beta1
62+
kind: EventListener
63+
metadata:
64+
name: github-owners-listener
65+
spec:
66+
triggers:
67+
- name: github-listener
68+
interceptors:
69+
- ref:
70+
name: "github"
71+
kind: ClusterInterceptor
72+
apiVersion: triggers.tekton.dev
73+
params:
74+
- name: "secretRef"
75+
value:
76+
secretName: github-secret
77+
secretKey: secretToken
78+
- name: "eventTypes"
79+
value: ["pull_request", "issue_comment"]
80+
- name: "githubOwners"
81+
value:
82+
enabled: true
83+
personalAccessToken:
84+
secretName: github-token
85+
secretKey: secretToken
86+
checkType: all
87+
...
88+
----
89+
+
90+
[NOTE]
91+
====
92+
The `checkType` parameter is used to specify the GitHub owners who need authentication. You can set its value to `orgMembers`, `repoMembers`, or `all`.
93+
====
94+
95+
. Save the configuration file.

0 commit comments

Comments
 (0)