diff options
| -rw-r--r-- | INSTALL-GITHUB-DEV | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/INSTALL-GITHUB-DEV b/INSTALL-GITHUB-DEV new file mode 100644 index 0000000..5fe38e6 --- /dev/null +++ b/INSTALL-GITHUB-DEV @@ -0,0 +1,88 @@ +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. + +0. Overview of the brep Github CI integration + +First we register our Github CI brep module 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 our Github app on their user or +organization 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 and connecting it to our local brep instance via a +the smee client (also run locally). + +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 our +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 stdout. + +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.) |