: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.opendev.org
:Puppet:
  * https://opendev.org/opendev/system-config
  * :git_file:`modules/openstack_project/manifests/gerrit.pp`
  * :git_file:`hiera/group/zuul-scheduler.yaml`
:Projects:
  * https://opendev.org/zuul/zuul
  * https://opendev.org/opendev/jeepyb
:Chat:
  * #openstack-infra on freenode

Overview
========

There are currently three different forms of interaction with GitHub.

* Gerrit Replication
* Pull Request Closer
* OpenDev 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:

OpenDev 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 configuring projects to use the OpenDev Zuul
App can be found in the :ref:`zuul` page at :ref:`zuul_github_projects`.

The OpenDev Zuul App is managed `OpenDev Zuul Settings Page`_ which is
available to admins of the `opendevorg Organization`_.

The OpenDev Zuul App has an ID, a Private key, a Webhook secret and a set of
OAuth Credentials which are all stored in hiera.

The ID is a numerical identifier found on the App settings page labeled **ID**.
The ID is placed into the ``app_id`` field in the ``github``
entry in ``zuul_connection_secrets`` for the ``zuul-scheduler`` group.

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 content is stored as ``zuul_github_app_key`` in private hiera
and is written to ``/etc/zuul/github.key``. That path is placed into
``app_key`` field in the ``github`` entry in ``zuul_connections`` for the
``zuul-scheduler`` group.

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://zuul.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
``zuul-scheduler`` group.

The OAuth credentials for the OpenDev Zuul App are currently unused.

.. _GitHub App: https://developer.github.com/apps/
.. _OpenDev Zuul Settings Page: https://github.com/organizations/opendevorg/settings/apps/opendev-zuul.
.. _opendevorg Organization: https://github.com/organizations/opendevorg/settings/profile