Document Zuul v3 GitHub integration

We have GitHub integration for Zuul v3, so we should have documentation
of that integration.

Change-Id: Ibbd41a43338f1d439d47aa13ced60ed477a6bbef

doc/source/gerrit.rst

@@ -113,6 +113,8 @@ using::
     --email openstack-infra@lists.openstack.org \
     --ssh-key - openstack-project-creator
 
+.. _gerrit_github_integration:
+
 GitHub Integration
 ==================
 

doc/source/github.rst

@@ -0,0 +1,86 @@
+:title: GitHub
+
+.. _github:
+
+GitHub
+######
+
+GitHub is a code-hosting platform that, while not used for OpenStack
+development, is nonetheless frequently enough used by non-OpenStack projects
+that OpenStack has tooling interactions with it.
+
+At a Glance
+===========
+
+:Hosts:
+  * review.openstack.org
+:Puppet:
+  * https://git.openstack.org/cgit/openstack-infra/system-config/tree/
+  * :file:`modules/openstack_project/manifests/gerrit.pp`
+  * :file:`hiera/fqdn/zuulv3.openstack.org.yaml`
+:Projects:
+  * https://git.openstack.org/cgit/openstack-infra/zuul
+  * https://git.openstack.org/cgit/openstack-infra/jeepyb
+:Chat:
+  * #openstack-infra on freenode
+
+Overview
+========
+
+There are currently three different forms of interaction with GitHub.
+
+* Gerrit Replication
+* Pull Request Closer
+* OpenStack Zuul App
+
+Gerrit Replication
+------------------
+
+Each project in gerrit is replicated on merge to a corresponding repository
+in GitHub. More information on this can be found in the :ref:`gerrit`
+document at :ref:`gerrit_github_integration`.
+
+Pull Request Closer
+-------------------
+
+A cronjob is run that looks for Pull Requests that have been erroneously
+submitted and closes them with a helpful message pointing people to the
+documentation on `Contributing to OpenStack`_. More information on this can
+be found in the :ref:`jeepyb` document at :ref:`closing_pull_requests`.
+
+.. _Contributing to OpenStack: http://docs.openstack.org/infra/manual/developers.html#getting-started
+
+.. _openstack_zuul_app:
+
+OpenStack Zuul App
+------------------
+
+Zuul v3 is integrated with GitHub by way of a `GitHub App`_. This is done to
+enable OpenStack to test integration with external projects that use GitHub
+for development. Information on onfiguring projects to use the OpenStack Zuul
+App can be found in the :ref:`zuul` page at :ref:`zuul_github_projects`.
+
+The OpenStack Zuul App is managed `OpenStack Zuul Settings Page`_ which is
+available to admins of the `openstack-infra Organization`_.
+
+The OpenStack Zuul App has a Private key, a Webhook secret and a set of OAuth
+Credentials which are all stored in hiera.
+
+The Private key can only be retrieved when it is generated, so in the case it
+is lost a new one must be generated and the resulting value put into hiera.
+The Private key is placed into the ``api_token`` field in the ``github``
+entry in ``zuul_connection_secrets`` for the ``zuulv3.openstack.org`` FQDN.
+
+GitHub sends JSON payloads via HTTP POST to the URL configured in the Webhook
+URL setting. The current value of this setting for Zuul v3 is:
+https://zuulv3.openstack.org/connection/github/payload. It includes the
+configured "Webhook Secret" so that Zuul can verify that the payload actually
+did come from GitHub. The "Webhook Secret" is placed into the ``webhook_token``
+field in the ``github`` entry in ``zuul_connection_secrets`` for the
+``zuulv3.openstack.org`` FQDN.
+
+The OAuth credentials for the OpenStack Zuul App are currently unused.
+
+.. _GitHub App: https://developer.github.com/apps/
+.. _OpenStack Zuul Settings Page: https://github.com/organizations/openstack-infra/settings/apps/openstack-zuul.
+.. _openstack-infra Organization: https://github.com/organizations/openstack-infra/settings/profile

doc/source/jeepyb.rst

@@ -159,6 +159,8 @@ in reviews.
 Periodic Tasks
 ==============
 
+.. _closing_pull_requests:
+
 Closing Github Pull Requests
 ----------------------------
 

doc/source/systems.rst

@@ -43,6 +43,7 @@ Major Systems
    firehose
    firehose_schema
    pholio
+   github
 
 .. NOTE(dhellmann): These projects were not listed above, or in any
    other toctree, which breaks the build. It's not clear why they were

doc/source/zuul.rst

@@ -177,3 +177,29 @@ manner, Ansible logs are available in the launcher-debug log file on
 the launcher host.  You may use the Zuul build UUID to track
 assignment of a given job from the Zuul scheduler to the Zuul launcher
 used by that job.
+
+.. note:: The following is Zuul v3 only, so is a little forward-looking.
+
+.. _zuul_github_projects:
+
+GitHub Projects
+===============
+
+OpenStack does not use GitHub for development purposes, but there are some
+non-OpenStack projects in the broader ecosystem that we care about who do.
+When we are interested in setting up jobs in Zuul to test the interaction
+between OpenStack projects and those ecosystem projects, we can add the
+OpenStack Zuul GitHub app to those projects, then configure them in Zuul.
+
+In order to add the GitHub app to a project, an admin on that project should
+nagivate to the `OpenStack Zuul`_ app in the GitHub UI. From there they can
+click "Install", then choose the project or organization they want to install
+the App on.
+
+The repository then needs to be added to the `zuul/main.yaml` file before Zuul
+can be configured to actually run jobs on it.
+
+Information about the configuration of the OpenStack Zuul App itself can be
+found on the :ref:`github` page at :ref:`openstack_zuul_app`.
+
+.. _OpenStack Zuul: https://github.com/apps/openstack-zuul