diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst index b6d9704c42..c009536e0d 100644 --- a/doc/source/gerrit.rst +++ b/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 ================== diff --git a/doc/source/github.rst b/doc/source/github.rst new file mode 100644 index 0000000000..e75dd2cba3 --- /dev/null +++ b/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 diff --git a/doc/source/jeepyb.rst b/doc/source/jeepyb.rst index 2c992412d6..6d2873cd06 100644 --- a/doc/source/jeepyb.rst +++ b/doc/source/jeepyb.rst @@ -159,6 +159,8 @@ in reviews. Periodic Tasks ============== +.. _closing_pull_requests: + Closing Github Pull Requests ---------------------------- diff --git a/doc/source/systems.rst b/doc/source/systems.rst index 1c4c669a40..ad6c885f2b 100644 --- a/doc/source/systems.rst +++ b/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 diff --git a/doc/source/zuul.rst b/doc/source/zuul.rst index 781d4d9758..0a783533b8 100644 --- a/doc/source/zuul.rst +++ b/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