1 files changed, 90 insertions, 0 deletions
diff --git a/INSTALL-GITHUB-DEV b/INSTALL-GITHUB-DEV
new file mode 100644
index 0000000..45f4b9b
--- /dev/null
+++ b/INSTALL-GITHUB-DEV
@@ -0,0 +1,90 @@
+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.)