Merge "Update docs on github connection settings" into feature/zuulv3
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/