docs(github bot): outline github bot setup (#17)

A bit tedious to setup.

README.md

@@ -188,6 +188,116 @@ Changing the size of a `varchar` field requires an `ACCESS EXCLUSIVE` lock.
 Using a text field with a `CHECK CONSTRAINT` makes it easier to change the
 max length. See the `constraint-missing-not-valid` rule.
 
+## Bot Setup
+
+Squawk works as a CLI tool but can also create comments on GitHub Pull
+Requests using the `upload-to-github` subcommand.
+
+Here's an example comment created by `squawk` using the `example.sql` in the repo:
+
+<https://github.com/sbdchd/squawk/pull/14#issuecomment-647009446>
+
+### Create a new app
+
+Squawk needs a corresponding GitHub App so it can talk to GitHub.
+
+1. Create the app
+
+   - head over to <https://github.com/settings/apps/new>
+
+   - add an app name & homepage url
+
+   - Uncheck the `active` checkbox under Webhook
+
+   - add permissions
+
+   | name          | kind  | why               |
+   | ------------- | ----- | ----------------- |
+   | Pull Requests | Write | to comment on PRs |
+
+   hit create and copy the `App ID` under the "About" section
+
+   url should be: https://github.com/settings/apps/$YOUR_APP_NAME
+
+2. Head down the the bottom of the page under the "Private Keys" section and
+   hit "Generate a private key"
+
+   The key should automatically download after a couple seconds. Hold onto this key, we'll need it later.
+
+   Now we have an `App ID` and a `Private Key`, now we need to install the app
+
+3. Install the app & get the Install ID
+
+   Head to <https://github.com/settings/apps/$YOUR_APP_NAME/installations> and hit "Install"
+
+   GitHub should have redirected you to the <https://github.com/settings/installations/$INSTALL_ID> page where `$INSTALL_ID` is some number.
+
+   Save this ID for later.
+
+   Now we have our `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY`,
+   `GITHUB_INSTALL_ID`, and `GITHUB_BOT_NAME`.
+
+   Squawk needs the pull request related values: `GITHUB_REPO_NAME`,
+   `GITHUB_REPO_OWNER`, and `GITHUB_PR_NUMBER`.
+
+   Where to find these varies depending how you're running squawk, but for the
+   next step I'm assuming you're running Squawk as a CircleCI job.
+
+4. Finding the Pull Request variables
+
+   ### CircleCI
+
+   <https://circleci.com/docs/2.0/env-vars/#built-in-environment-variables>
+
+   `CIRCLE_PULL_REQUEST` has the content we need
+
+   example: `https://github.com/recipeyak/recipeyak/pull/567`
+
+   Now we need to split this to get the repo name, repo owner, and pull
+   requeset id.
+
+   With a bit of help from
+
+   ```sh
+   echo "https://github.com/recipeyak/recipeyak/pull/567" | awk -F/ '{print $4 " " $5 " " $7}'
+
+   recipeyak recipeyak 567
+   ```
+
+   ```sh
+   GITHUB_REPO_OWNER=$(echo $CIRCLE_PULL_REQUEST | awk -F/ '{print $4}')
+   GITHUB_REPO_NAME=$(echo $CIRCLE_PULL_REQUEST | awk -F/ '{print $5}')
+   GITHUB_PR_NUMBER=$(echo $CIRCLE_PULL_REQUEST | awk -F/ '{print $7}')
+   ```
+
+5. Conclusion
+
+   Wrapping it all up we should have the following env vars:
+
+   ```sh
+   GITHUB_APP_ID= # fill in with id found in step 5
+   GITHUB_INSTALL_ID= # fill in with id found in step 7
+   GITHUB_BOT_NAME= # fill in with your bot name from step 2
+   # downloaded via step 6, your key will have a different name
+   GITHUB_PRIVATE_KEY=$(cat ./cool-bot-name.private-key.pem)
+   GITHUB_REPO_OWNER=$(echo $CIRCLE_PULL_REQUEST | awk -F/ '{print $4}')
+   GITHUB_REPO_NAME=$(echo $CIRCLE_PULL_REQUEST | awk -F/ '{print $5}')
+   GITHUB_PR_NUMBER=$(echo $CIRCLE_PULL_REQUEST | awk -F/ '{print $7}')
+   ```
+
+   We can pass this into the env before running squawk or we can translate
+   them to the command line flag. What's ever easiest for you.
+
+   An example run will look like the following (assuming the env vars are set):
+
+   ```sh
+   squawk upload-to-github example.sql
+   ```
+
+   which creates a comment like the following:
+
+   <https://github.com/sbdchd/squawk/pull/14#issuecomment-647009446>
+
 ## prior art
 
 - <https://github.com/erik/squabble>