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).

0.0 User configuration

This GitHub CI integration only has one user-configurable option:
warning=<success|failure> (whether or not to fail on warnings).

In order not to have to support repository configuration files the live
deployment will consist of two registered GitHub apps with the same webhook
URL (i.e., the same brep instance) but different query parameters: one with
warning=success and the other with warning=failure. The app id is passed so
that we know which private key to use (the key cannot be shared between apps).

Only a single GitHub app is required during development however.

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

2. Set up the webhook proxy

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

  https://smee.io/7stvNqVgyQRlIhbY

This will be used in the GitHub app's webhook URL below.

3. Register the GitHub app

GitHub reference: Registering a GitHub App (note: somewhat out of date)
https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app

At this stage the only settings we need to update are:

- App name
- Homepage URL (https://build2.org)
- Webhook
  - URL: set to the webhook proxy URL
  - Secret (e.g. "deadbeef")
  - Leave SSL verification enabled
- Repository permissions
  - Checks: RW
  - Metadata (mandatory): RO
  - Pull requests: RO
  - Contents: RO (for Push events)
- Subscribed events
  - Check suite
  - Pull request
  - Push

Click "Create GitHub App" button. When the page reloads:

- Note the app id (e.g. 12345).
- Append "?app-id=12345&warning=failure" to the webhook URL.
- Scroll to Private keys and generate a private key. The file will be
  downloaded by the browser.

4. 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.

5. Configure brep

In brep-module.conf:

- Set the webhook secret from the GitHub app settings:

  ci-github-app-webhook-secret "deadbeef"

- Associate the GitHub app id with the path of the private key downloaded
  above:

  ci-github-app-id-private-key 12345=path/to/private-key.pem

6. Forward GitHub webhooks to a local brep instance

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.

A webhook can be redelivered from the smee.io channel page or the app's
advanced settings page on GitHub so no need to repeatedly push to the
repository.

Both the smee.io channel and the GitHub app's advanced settings show the JSON
payloads of delivered webhooks. smee.io's presentation is better but the
GitHub app page also shows the HTTP headers. Wireshark might be better in both
aspects but can't redeliver webhooks.

7. Test scenarios

- Branch push (BP).

  - Success (observe check runs state transitions). Test with 2 build configs.
  - Failure (observe check runs state transitions).
  - Push new commit to branch.
  - Re-requested check suite.
  - Re-requested check run (observe check run state transitions).
  - Re-requested check run but tenant archived.
  - Cancel previous check suite on forced push.
  - Head commit shared with another BP.
  - Cancel previous check suite on forced push with shared previous commit.

- Pull request (PR).

  - Local PR.

    - Success.
    - Failure.
    - Push new commit to head.
    - Re-requested check suite.
    - Re-requested check run.
    - Head shared with BP.
    - Not meargeable/head behind base.

  - Remote PR.

    - Success.
    - Failure.
    - Push new commit to head.
    - Re-requested check suite.
    - Re-requested check run.
    - Head shared with another remote PR.
    - Cancel previous check suite on head move.