From cdddbb89f38971b9ace87b1a08eddcf5932c338a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Sat, 30 Oct 2021 09:37:42 +0200
Subject: [PATCH 1/3] docs: improve github status plugin documentation

---
 doc/manual/src/plugins/README.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/manual/src/plugins/README.md b/doc/manual/src/plugins/README.md
index 25ea6e3a..4212f429 100644
--- a/doc/manual/src/plugins/README.md
+++ b/doc/manual/src/plugins/README.md
@@ -111,7 +111,7 @@ Sets GitHub CI status.
 - `githubstatus.[].jobs`
 
 Regular expression for jobs to match in the format `project:jobset:job`.
-Defaults to `*:*:*`.
+This field is required and has no default value.
 
 - `githubstatus.[].excludeBuildFromContext`
 
@@ -140,15 +140,18 @@ status we want to report. Can be repeated.
 
 Verbatim contents of the Authorization header. See
 [GitHub documentation](https://developer.github.com/v3/#authentication) for
-details.
+details. This field is only used if `github_authorization.<repo-owner>` is not set.
+
 
 ### Example
 
 ```xml
 <githubstatus>
   jobs = test:pr:build
+  ## This example will match all jobs
+  #jobs = .*
   inputs = src
-  authorization = Basic notgivingyoumypasswordosorry
+  authorization = Bearer gha-secret😱secret😱secret😱
   excludeBuildFromContext = 1
 </githubstatus>
 ```

From 70f1db27624af3354f4134681851a42244b5aa60 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Sat, 30 Oct 2021 09:37:57 +0200
Subject: [PATCH 2/3] docs: improve github refs documentation

---
 doc/manual/src/plugins/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/manual/src/plugins/README.md b/doc/manual/src/plugins/README.md
index 4212f429..b5486fdb 100644
--- a/doc/manual/src/plugins/README.md
+++ b/doc/manual/src/plugins/README.md
@@ -99,7 +99,7 @@ GitHub following a certain naming scheme.
 
 ### Configuration options
 
-- `github_endpoint`
+- `github_endpoint` (defaults to https://api.github.com)
 - `github_authorization.<repo-owner>`
 
 ## Github status

From 1593e0212ec966b37e91de7a73387ffc4e3a0fa8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Sat, 30 Oct 2021 09:35:01 +0200
Subject: [PATCH 3/3] docs: document github webhooks

---
 doc/manual/src/SUMMARY.md  |  1 +
 doc/manual/src/webhooks.md | 13 +++++++++++++
 2 files changed, 14 insertions(+)
 create mode 100644 doc/manual/src/webhooks.md

diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md
index b315aeff..80e73112 100644
--- a/doc/manual/src/SUMMARY.md
+++ b/doc/manual/src/SUMMARY.md
@@ -8,6 +8,7 @@
 - [Plugins](./plugins/README.md)
   - [Declarative Projects](./plugins/declarative-projects.md)
 - [Using the external API](api.md)
+- [Webhooks](webhooks.md)
 - [Monitoring Hydra](./monitoring/README.md)
 
 ## Developer's Guide
diff --git a/doc/manual/src/webhooks.md b/doc/manual/src/webhooks.md
new file mode 100644
index 00000000..2b26cd61
--- /dev/null
+++ b/doc/manual/src/webhooks.md
@@ -0,0 +1,13 @@
+# Webhooks
+
+Hydra can be notified by github's webhook to trigger a new evaluation when a
+jobset has a github repo in its input.
+To set up a github webhook go to `https://github.com/<yourhandle>/<yourrepo>/settings` and in the `Webhooks` tab
+click on `Add webhook`.
+
+- In `Payload URL` fill in `https://<your-hydra-domain>/api/push-github`.
+- In `Content type` switch to `application/json`.
+- The `Secret` field can stay empty.
+- For `Which events would you like to trigger this webhook?` keep the default option for events on `Just the push event.`.
+
+Then add the hook with `Add webhook`.