This document explains how to get GitHub webhooks (a notification that an
event such as a push has occurred on a repository) delivered to a
locally-running instance of brep (currently to initiate a CI job).

0. Overview of the brep GitHub CI integration

First we register our GitHub CI brep instance as a GitHub app. This GitHub app
essentially consists of an app name, the URL we want webhooks to be delivered
to, permissions required on users' repositories, event subscriptions, and
various authentication-related settings.

Once registered, GitHub users can install this GitHub app on their user's or
organization's accounts, optionally restricting its access to specific
repositories.

Once installed on a repository, GitHub will send webhook requests to our app's
webhook URL when, for example, code is pushed or a pull request is created
(the specifics depending on the events our app is subscribed to).

For development we need these webhooks delivered to our locally-running brep
instance. This is achieved by setting the GitHub app's webhook URL to that of
the webhook proxy smee.io (as recommended by GitHub) and connecting it to our
local brep instance via the locally-run smee client (a Node application).

1. Follow the instructions in INSTALL-DEV to get brep set up.

2. Register the GitHub app

GitHub doc: Registering a GitHub App (note that that doc is a bit out of date)
https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app

Skip the steps marked "optional" and leave authorization-related settings at
their defaults.

@@ TODO Update authentication-related info once better understood.

At this stage the only settings important to us are:

- App name
- Webhook URL (updated later -- leave webhooks deactivated for now)
- Repository permissions
  - Checks: RW
  - Pull requests: RO
  - Contents: RO
  - Metadata: RO
- Subscribed events
  - Check suite
  - Check run
  - Pull request

3. Install the GitHub app

GitHub doc: Installing your own GitHub App
https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app

It would probably make sense to install it to your own user account and
restrict its access to a test repository.

4. Forward GitHub webhooks to a local brep instance

Go to https://smee.io/ and start a new channel. Note the webhook proxy URL,
which will look something like

  https://smee.io/7stvNqVgyQRlIhbY

Set the GitHub app's webhook URL to this proxy URL.

Install the smee client:

  $ npm install --global smee-client

Start brep.

Start the smee client, passing the webhook proxy URL with --url and the brep
GitHub CI endpoint's URL with --target:

  $ smee --url https://smee.io/7stvNqVgyQRlIhbY \
         --target http://127.0.0.1/pkg?ci-github

Trigger a webhook delivery from GitHub by pushing a commit to a repository the
GitHub app is installed in. You should see the webhook delivery on the smee.io
channel page and the smee client will also print something to terminal.

Any webhook delivery can be redelivered by clicking a button on the smee.io
channel page (or the app's advanced settings page on GitHub) so no need to
repeatedly push to the repository.

You can also see the HTTP headers and JSON payload of delivered webhooks on
both the GitHub app's advanced settings page and the smee.io channel page, but
smee.io's presentation is much better. (There's also wireshark of course.)