Merge pull request #58113 from shipsing/RHDEVDOCS-5061

RHDEVDOCS-5061: Documenting pull request capabilities in GitHub Inter…

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

@@ -70,6 +70,12 @@ include::modules/op-enabling-monitoring-of-event-listeners-for-triggers-for-user
 
 * xref:../../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects]
 
+include::modules/op-configuring-pull-request-capabilities-in-GitHub-interceptor.adoc[leveloffset=+1]
+
+include::modules/op-filtering-pull-requests-using-GitHub-interceptor.adoc[leveloffset=+2]
+
+include::modules/op-validating-pull-requests-using-GitHub-interceptors.adoc[leveloffset=+2]
+
 [role="_additional-resources"]
 [id="pipeline-addtl-resources"]
 == Additional resources

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

@@ -0,0 +1,13 @@
+// Ths module is included in the following assembly:
+//
+// *cicd/pipelines/creating-applications-with-cicd-pipelines.adoc
+
+:_content-type: CONCEPT
+[id="op-configuring-pull-request-capabilities-in-GitHub-interceptor_{context}"]
+= Configuring pull request capabilities in GitHub Interceptor
+
+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. 
+In {pipelines-title}, you can use the following capabilities of GitHub Interceptor:
+
+* Filter pull request events based on the files that have been changed
+* Validate pull requests based on configured GitHub owners

modules/op-filtering-pull-requests-using-GitHub-interceptor.adoc

@@ -0,0 +1,88 @@
+// This module is included in the following assembly:
+//
+// *cicd/pipelines/creating-applications-with-cicd-pipelines.adoc
+
+:_content-type: PROCEDURE
+[id="op-filtering-pull-requests-using-GitHub-interceptor_{context}"]
+= Filtering pull requests using GitHub Interceptor
+
+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.
+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. 
+
+.Prerequistes
+* You have installed the {pipelines-title} Operator.
+
+.Procedure
+. Perform one of the following steps: 
+* For a public GitHub repository, set the value of the `addChangedFiles` parameter to `true` in the YAML configuration file shown below:
++
+[source,yaml]
+----
+apiVersion: triggers.tekton.dev/v1beta1
+kind: EventListener
+metadata:
+  name: github-add-changed-files-pr-listener
+spec:
+  triggers:
+    - name: github-listener
+      interceptors:
+        - ref:
+            name: "github"
+            kind: ClusterInterceptor
+            apiVersion: triggers.tekton.dev
+          params:
+          - name: "secretRef"
+            value:
+              secretName: github-secret
+              secretKey: secretToken
+          - name: "eventTypes"
+            value: ["pull_request", "push"]
+          - name: "addChangedFiles"
+            value:
+              enabled: true
+        - ref:
+            name: cel
+          params:
+          - name: filter
+            value: extensions.changed_files.matches('controllers/')
+...
+----
+
+* 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:
++
+[source,yaml]
+----
+apiVersion: triggers.tekton.dev/v1beta1
+kind: EventListener
+metadata:
+  name: github-add-changed-files-pr-listener
+spec:
+  triggers:
+    - name: github-listener
+      interceptors:
+        - ref:
+            name: "github"
+            kind: ClusterInterceptor
+            apiVersion: triggers.tekton.dev
+          params:
+          - name: "secretRef"
+            value:
+              secretName: github-secret
+              secretKey: secretToken
+          - name: "eventTypes"
+            value: ["pull_request", "push"]
+          - name: "addChangedFiles"
+            value:
+              enabled: true
+              personalAccessToken:
+                secretName: github-pat
+                secretKey: token
+        - ref:
+            name: cel
+          params:
+          - name: filter
+            value: extensions.changed_files.matches('controllers/')
+...
+----
+
+. Save the configuration file.

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

@@ -0,0 +1,95 @@
+// This module is included in the following assembly:
+//
+// *cicd/pipelines/creating-applications-with-cicd-pipelines.adoc
+
+:_content-type: PROCEDURE
+[id="op-validating-pull-requests-using-GitHub-interceptors_{context}"]
+= Validating pull requests using GitHub Interceptors
+
+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.
+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. 
+
+[NOTE]
+====
+Owners are configured in an `OWNERS` file at the root of the repository.
+====
+
+.Prerequisites
+* You have installed the {pipelines-title} Operator.
+
+.Procedure
+. Create a secret string value.
+. Configure the GitHub webhook with that value.
+. Create a Kubernetes secret named `secretRef` that contains your secret value.
+. Pass the Kubernetes secret as a reference to your GitHub Interceptor.
+. Create an `owners` file and add the list of approvers into the `approvers` section.
+. Perform one of the following steps: 
+* For a public GitHub repository, set the value of the `githubOwners` parameter to `true` in the YAML configuration file shown below:
++
+[source,yaml]
+----
+apiVersion: triggers.tekton.dev/v1beta1
+kind: EventListener
+metadata:
+  name: github-owners-listener
+spec:
+  triggers:
+    - name: github-listener
+      interceptors:
+        - ref:
+            name: "github"
+            kind: ClusterInterceptor
+            apiVersion: triggers.tekton.dev
+          params:
+            - name: "secretRef"
+              value:
+                secretName: github-secret
+                secretKey: secretToken
+            - name: "eventTypes"
+              value: ["pull_request", "issue_comment"]
+            - name: "githubOwners"
+              value: 
+                enabled: true
+                checkType: none
+...
+----
+
+* 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:
++
+[source,yaml]
+----
+apiVersion: triggers.tekton.dev/v1beta1
+kind: EventListener
+metadata:
+  name: github-owners-listener
+spec:
+  triggers:
+    - name: github-listener
+      interceptors:
+        - ref:
+            name: "github"
+            kind: ClusterInterceptor
+            apiVersion: triggers.tekton.dev
+          params:
+            - name: "secretRef"
+              value:
+                secretName: github-secret
+                secretKey: secretToken
+            - name: "eventTypes"
+              value: ["pull_request", "issue_comment"]
+            - name: "githubOwners"
+              value: 
+                enabled: true
+                personalAccessToken:
+                  secretName: github-token
+                  secretKey: secretToken
+                checkType: all  
+...
+----
++
+[NOTE]
+====
+The `checkType` parameter is used to specify the GitHub owners who need authentication. You can set its value to `orgMembers`, `repoMembers`, or `all`.
+====
+
+. Save the configuration file.