Merge pull request #1695 from ehuss/gh-api-docs

Add more documentation on setting up local testing.

README.md

@@ -34,38 +34,86 @@ Some developers may settle with testing in production as the risks tend to be lo
 
 The general overview of what you will need to do:
 
-1. Install Postgres. Look online for any help with installing and setting up Postgres (particularly if you need to create a user and set up permissions).
-2. Create a database: `createdb triagebot`
-3. Provide a way for GitHub to access the Triagebot webserver.
-   There are various ways to do this (such as placing it behind a proxy, or poking holes in your firewall).
-   Or, you can use a service such as https://ngrok.com/ to access on your local dev machine via localhost.
-   Installation is fairly simple, though requires setting up a (free) account.
-   Run the command `ngrok http 8000` to forward to port 8000 on localhost.
-4. Create a GitHub repo to run some tests on.
-5. Configure the webhook in your GitHub repo.
-   I recommend at least skimming the [GitHub webhook documentation](https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks) if you are not familiar with webhooks. In short:
-
-   1. Go to the settings page.
-   2. Go to the webhook section.
-   3. Click "Add webhook"
-   4. Include the settings:
-
-      - Payload URL: This is the URL to your Triagebot server, for example http://7e9ea9dc.ngrok.io/github-hook. This URL is displayed when you ran the `ngrok` command above.
-      - Content type: application/json
-      - Secret: Enter a shared secret (some longish random text)
-      - Events: "Send me everything"
-6. Configure the `.env` file:
+1. Create a repo on GitHub to run tests on.
+2. [Configure a database](#configure-a-database)
+3. [Configure webhook forwarding](#configure-webhook-forwarding)
+4. Configure the `.env` file:
 
    1. Copy `.env.sample` to `.env`
    2. `GITHUB_API_TOKEN`: This is a token needed for Triagebot to send requests to GitHub. Go to GitHub Settings > Developer Settings > Personal Access Token, and create a new token. The `repo` permission should be sufficient.
       If this is not set, Triagebot will also look in `~/.gitconfig` in the `github.oauth-token` setting.
-   3. `DATABASE_URL`: This is the URL to the Postgres database. Something like `postgres://eric@localhost/triagebot` should work, replacing `eric` with your username.
+   3. `DATABASE_URL`: This is the URL to the database. See [Configuring a database](#configuring-a-database).
    4. `GITHUB_WEBHOOK_SECRET`: Enter the secret you entered in the webhook above.
    5. `RUST_LOG`: Set this to `debug`.
 
-7. Run `cargo run --bin triagebot`. This starts the http server listening on port 8000.
-8. Add a `triagebot.toml` file to the main branch of your GitHub repo with whichever services you want to try out.
-9. Try interacting with your repo, such as issuing `@rustbot` commands or interacting with PRs and issues (depending on which services you enabled in `triagebot.toml`). Watch the logs from the server to see what's going on.
+5. Run `cargo run --bin triagebot`. This starts the http server listening for webhooks on port 8000.
+6. Add a `triagebot.toml` file to the main branch of your GitHub repo with whichever services you want to try out.
+7. Try interacting with your repo, such as issuing `@rustbot` commands or interacting with PRs and issues (depending on which services you enabled in `triagebot.toml`). Watch the logs from the server to see what's going on.
+
+### Configure a database
+
+To use Postgres, you will need to install it and configure it:
+
+1. Install Postgres. Look online for any help with installing and setting up Postgres (particularly if you need to create a user and set up permissions).
+2. Create a database: `createdb triagebot`
+3. In the `.env` file, set the `DATABASE_URL`:
+
+   ```sh
+   DATABASE_URL=postgres://eric@localhost/triagebot
+   ```
+
+   replacing `eric` with the username on your local system.
+
+### Configure webhook forwarding
+
+I recommend at least skimming the [GitHub webhook documentation](https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks) if you are not familiar with webhooks.
+In order for GitHub's webhooks to reach your triagebot server, you'll need to figure out some way to route them to your machine.
+There are various options on how to do this.
+You can poke holes into your firewall or use a proxy, but you shouldn't expose your machine to the the internet.
+There are various services which help with this problem.
+These generally involve running a program on your machine that connects to an external server which relays the hooks into your machine.
+There are several to choose from:
+
+* [gh webhook](#gh-webhook) — This is a GitHub-native service. This is the easiest to use.
+* [ngrok](#ngrok) — This is pretty easy to use, but requires setting up a free account.
+* <https://smee.io/> — This is another service recommended by GitHub.
+* <https://localtunnel.github.io/www/> — This is another service recommended by GitHub.
+
+#### gh webhook
+
+The [`gh` CLI](https://github.com/cli/cli) is the official CLI tool which I highly recommend getting familiar with.
+There is an official extension which provides webhook forwarding and also takes care of all the configuration.
+See [cli/gh-webhook](https://docs.github.com/en/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli) for more information on installing it.
+
+This is super easy to use, and doesn't require manually configuring webhook settings.
+The command to run looks something like:
+
+```sh
+gh webhook forward --repo=ehuss/triagebot-test --events=* \
+  --url=http://127.0.0.1:8000/github-hook --secret somelongsekrit
+```
+
+Where the value in `--secret` is the secret value you place in `GITHUB_WEBHOOK_SECRET` in the `.env` file, and `--repo` is the repo you want to test against.
+
+#### ngrok
+
+The following is an example of using <https://ngrok.com/> to provide webhook forwarding.
+You need to sign up for a free account, and also deal with configuring the GitHub webhook settings.
+
+1. Install ngrok.
+2. Run `ngrok http 8000`. This will forward webhook events to localhost on port 8000.
+3. Configure GitHub webhooks in the test repo you created.
+   In short:
+
+   1. Go to the settings page for your GitHub repo.
+   2. Go to the webhook section.
+   3. Click "Add webhook"
+   4. Include the settings:
+
+      * Payload URL: This is the URL to your Triagebot server, for example http://7e9ea9dc.ngrok.io/github-hook. This URL is displayed when you ran the `ngrok` command above.
+      * Content type: application/json
+      * Secret: Enter a shared secret (some longish random text)
+      * Events: "Send me everything"
 
 ## License