Add documentation for github commit status

docs/guides/notifications.md

@@ -102,3 +102,58 @@ When the verbosity is set to `info`, the controller will alert if:
 * an error occurs
 
 ![info alert](../diagrams/slack-info-alert.png)
+
+## GitHub commit status
+
+The GitHub provider is a special kind of notification provider that based on the
+state of a Kustomization resource, will update the
+[commit status](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks) for the currently reconciled commit id.
+
+The resulting status will contain information from the event in the format `{{ .Kind }}/{{ .Name }} - {{ .Reason }}`.
+![github commit status](../diagrams/github-commit-status.png)
+
+It is important to note that the referenced provider needs to refer to the
+same GitHub repository as the Kustomization originates from. If these do
+not match the notification will fail as the commit id will not be present.
+
+```yaml
+apiVersion: notification.toolkit.fluxcd.io/v1alpha1
+kind: Provider
+metadata:
+  name: podinfo
+  namespace: gitops-system
+spec:
+  type: github
+  channel: general
+  address: https://github.com/stefanprodan/podinfo
+  secretRef:
+    name: github
+---
+apiVersion: notification.toolkit.fluxcd.io/v1alpha1
+kind: Alert
+metadata:
+  name: podinfo
+  namespace: gitops-system
+spec:
+  providerRef:
+    name: podinfo
+  eventSeverity: info
+  eventSources:
+    - kind: Kustomization
+      name: podinfo
+      namespace: gitops-system
+```
+
+The secret referenced in the provider is expected to contain a [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)
+to authenticate with the GitHub API.
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: github
+  namespace: gitops-system
+data:
+  token: <token>
+```
+
+