Update docs on github connection settings
There were two essential settings completely missing. Add them. Also add
some text about what things are called in the UI, since we're using
completely different words in the Zuul config.
Change-Id: Ibead129aeab137154fe58f7db8d359f565868781
diff --git a/doc/source/admin/drivers/github.rst b/doc/source/admin/drivers/github.rst
index 9740292..5075f80 100644
--- a/doc/source/admin/drivers/github.rst
+++ b/doc/source/admin/drivers/github.rst
@@ -22,18 +22,35 @@
Connection Configuration
------------------------
+There are two forms of operation. Either the Zuul installation can be
+configured as a `Github App`_ or it can be configured as a Webhook.
+
+If the `Github App`_ approach is taken, the config settings ``app_id`` and
+``app_key`` are required. If the Webhook approach is taken, the ``api_token``
+setting is required.
+
The supported options in zuul.conf connections are:
**driver=github**
+**app_id**
+ App ID if you are using a GitHub App. Can be found under the "Public Link"
+ on the right hand side labeled "ID".
+
+**app_key**
+ The Secret Key Zuul will use to create tokens for the API interactions.
+ In Github this is known as "Private key" and must be collected when
+ generated.
+
**api_token**
- API token for accessing GitHub.
+ API token for accessing GitHub if Zuul is configured with Webhooks.
See `Creating an access token for command-line use
<https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
**webhook_token**
Optional: Token for validating the webhook event payloads.
- If not specified, payloads are not validated.
+ If not specified, payloads are not validated. In the GitHub App Configuration
+ page, this is called "Webhook secret".
See `Securing your webhooks
<https://developer.github.com/webhooks/securing/>`_.
@@ -174,3 +191,5 @@
List of strings each representing an exact label name which should
be removed from the pull request by reporter. Only used for Pull
Request based events. ``unlabel: 'test failed'``
+
+.. _Github App: https://developer.github.com/apps/