From c0b71bbd32eb18a758573a9dec5651d40b4929ec Mon Sep 17 00:00:00 2001
From: Mateusz Szostok <szostok.mateusz@gmail.com>
Date: Fri, 11 Aug 2023 16:05:23 +0200
Subject: [PATCH] Update GitHub and Flux docs

---
 docs/configuration/source/github-events.md | 34 +++++++++++++++
 docs/usage/executor/flux.md                | 49 +++++++++++++++++++++-
 2 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/docs/configuration/source/github-events.md b/docs/configuration/source/github-events.md
index d0cbd1b9..7ff30418 100644
--- a/docs/configuration/source/github-events.md
+++ b/docs/configuration/source/github-events.md
@@ -164,6 +164,29 @@ By default, we use [conditional requests](https://docs.github.com/en/rest/overvi
 
 For a configured `refreshDuration` we call the [`/repos/{owner}/{repo}/pulls`](https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#list-pull-requests) endpoint for all registered repositories. It's configured to fetch 100 pull requests that were recently modified. We ignore all events that were already processed.
 
+#### Matching criteria
+
+If no matching criteria are specified, all pull requests will be reported. For example:
+
+```yaml
+repositories:
+  - name: owner/repo1
+    on:
+      pullRequests: []
+```
+
+To narrow down emitted events, you can specify at least one of the available criteria:
+
+- `types`: This is a list of pull request types for which the event should be triggered. The allowed types are: `open`, `closed`, `merged`.
+
+- `paths.include`: This is a list of file patterns for which the event should be triggered. It supports [Go regular expressions](https://github.com/google/re2/wiki/Syntax). For example: `["kustomize/.*"]`.
+
+- `paths.exclude`: This is a list of file patterns for which the event should not be triggered. It also supports [Go regular expressions](https://github.com/google/re2/wiki/Syntax). For example: `['.*\.js']`. This exclusion criteria takes precedence over `paths.include`.
+
+- `labels.include`: This is a list of label patterns for which the event should be triggered. It supports [Go regular expressions](https://github.com/google/re2/wiki/Syntax). For example: `["backend-.*"]`.
+
+- `labels.exclude`: This is a list of label patterns for which the event should not be triggered. It supports [Go regular expressions](https://github.com/google/re2/wiki/Syntax). For example: `['bug']`. This exclusion criteria takes precedence over `labels.include`.
+
 #### Templating
 
 You can customize the notification template with additional buttons:
@@ -187,6 +210,17 @@ This API is not built to serve real-time use cases. Depending on the time of day
 
 The Events API covers various event types. Refer to the [GitHub event types](https://docs.github.com/en/webhooks-and-events/events/github-event-types) page for more information.
 
+#### Matching criteria
+
+To retrieve relevant events, you must define at least one entry within the `events` property. For instance:
+
+```yaml
+events:
+  - type: "WatchEvent"
+```
+
+If you provide an empty list `events: []`, no events will be emitted.
+
 #### Templating
 
 The available fields for templating differ based on the event type. Refer to the [google/go-github](https://github.com/google/go-github/tree/899235e0a9d750d6fecf9048a676046d50f9d4a3/github) repository for dedicated event types.
diff --git a/docs/usage/executor/flux.md b/docs/usage/executor/flux.md
index 6ef934ca..c6104729 100644
--- a/docs/usage/executor/flux.md
+++ b/docs/usage/executor/flux.md
@@ -4,7 +4,8 @@ title: "Flux"
 sidebar_position: 5
 ---
 
-Botkube offers seamless execution of Flux CLI commands within your Kubernetes cluster. By default, Flux command execution is disabled. To enable it, refer to the [**Enabling plugin**](../../configuration/executor/flux.md#enabling-plugin) section.
+Botkube offers seamless execution of Flux CLI commands within your Kubernetes cluster. By default, Flux command execution is disabled. To enable it, refer to the [
+**Enabling plugin**](../../configuration/executor/flux.md#enabling-plugin) section.
 
 To execute the `flux` CLI commands, send a message in the channel where Botkube is present. For example:
 
@@ -87,3 +88,49 @@ extraObjects:
         name: flux-read-patch
         apiGroup: rbac.authorization.k8s.io
 ```
+
+### GitHub automation
+
+To enhance your workflow's efficiency, you can use the [GitHub Events](../../configuration/source/github-events.md) source for automatic notification of pull request events, complete with an integrated `flux diff` button.
+
+```yaml
+sources:
+  github-events:
+    displayName: "GitHub Events"
+    botkube/github-events:
+      enabled: true
+      config:
+        github:
+          auth:
+            accessToken: "ghp_" # GitHub PAT
+
+        repositories:
+          - name: { owner }/{name}
+            on:
+              pullRequests:
+                  - types: [ "open" ]
+                    paths:
+                      # Patterns for included file changes in pull requests.
+                      include: [ 'kustomize/.*' ]
+                    notificationTemplate:
+                      extraButtons:
+                        - displayName: "Flux Diff"
+                          commandTpl: "flux diff ks podinfo --path ./kustomize --github-ref {{ .HTMLURL }} "
+```
+
+Don't forget to incorporate the `github-events` source into your communication platform bindings. For instance:
+
+```yaml
+communications:
+  default-group:
+    socketSlack:
+      enabled: true
+      channels:
+        default:
+          name: random
+          bindings:
+            sources:
+              - github-events
+            executors:
+              - flux
+```