Document GitHub integration

1 files changed, 63 insertions, 17 deletions

diff --git a/api/services/github/README.md b/api/services/github/README.md
index 29bbd28..6d05a72 100644
--- a/api/services/github/README.md
+++ b/api/services/github/README.md
@@ -1,24 +1,70 @@
 # GitHub Integration
 
-This is my first integration with GitHub so it may not be optimal.
+The primary use case for the keymap editor supports an integration with GitHub
+to fetch, modify, and commit keymaps to any enabled repositories.
 
-I also wanted to keep things as simple as possible and take advantage of free
-hosting services so the web application is hosted on GitHub Pages and the
-backend is running on Heroku. For this reason there is no persistence or
-handling of GitHub's events. This means that every page load requires fetching
-your app installation and layout/keymap files.
+## Terminology
 
-## GitHub App
+* **App**
+    * A GitHub App is an integration that allows a third party to make requests
+      to GitHub's API as another user.
+    * As far as GitHub is concerned this would refer to the combination of the
+      backend and frontend software in this repo. To avoid confusion I'll try to
+      distinguish between the _GitHub App_ and the _Web App_.
+* **Installation**
+    * This is the user's agreement to let the _GitHub App_ perform activies on
+      their behalf.
+    * It specifies a selection or repositories (or all owned repos) that the
+      GitHub App may access.
 
-https://github.com/apps/zmk-keymap-editor
+## Configuration
 
-I wanted to minimize required permissions as it only needs to edit two files.
-The problem is that one of these files is `<shield name>.keymap` so having
-write permissions for any file is necessary. This could be simplified if ZMK
-keyboard used something like `keyboard.keymap` but I don't know if this breaks
-other use cases.
+All configuration is provided to the app via environment variables.
+_(See [The Twelve-Factor App](https://12factor.net/config))_
 
-Also, I've done very little testing. As of this writing I'm only a few hours
-out from having the first workable implementation so there has been very little
-testing. As an example, I haven't built in any handling for things like expiring
-access tokens.
+If you wish to create a local dev environment or your own hosted instance of the
+editor, create a GitHub app, copy `.env.template` to `.env`, and fill in the
+following config values:
+
+* `GITHUB_APP_ID`: the app id generated by GitHub
+* `GITHUB_APP_NAME`: the name you chose for the app
+* `GITHUB_CLIENT_ID`: client id generated by GitHub
+* `GITHUB_CLIENT_SECRET`: client secret generated by GitHub
+* `GITHUB_OAUTH_CALLBACK_URL`: the public URL that GitHub will use to complete
+  the OAuth flow. This will be somthing like
+  `https://<api public url>/github/authorize>`
+* `GITHUB_APP_PRIVATE_KEY`: _(optional)_ this is the RSA private key associated
+  with your GitHub app. You may either pass this in as an environment variable
+  or store it in `private-key.pem` in this repository's root.
+* `APP_BASE_URL`: this is the public hosted URL for the keymap editor static
+  application (e.g. `https://<username>.github.io/keymap-editor` if using
+  GitHub pages). Note that this app should have been built with
+  `ENABLE_GITHUB=true`.
+
+**Warning** committing any of these values to a git repository is strongly
+discouraged. For local development you may create `.env` and `private-key.pem`
+and these files will be ignored by default. When deploying the application your
+cloud provider (e.g. Heroku) should provide a way to securely define the needed
+environment variables.
+
+## Auth Flow
+
+When first authenticating a user to GitHub the following browser flows occur:
+
+1. Web app redirects browser to `https://$api/github/authorize`
+2. API redirects browser to GitHub auth URL with a callback
+    * Here GitHub will prompt the user to log in and to authorize the web app to
+      make API requests on the user's behalf.
+3. GitHub redirects the browser back to `https://$api/github/authorize` with an
+  authentication token.
+4. API redirects browser back to the web app with auth token.
+    * The web app will store the auth token locally and all further requests to
+      the API will be authenticated.
+5. Web app requests GitHub App installation info
+6. API returns installation info or `null` if the GitHub App is not installed.
+    * If the GitHub App is installed the flow can end here.
+7. Web app redirects browser to GitHub App Installation URL.
+    * Here the user is prompted by GitHub to install the application and select
+      one or more (or all) repositories to enable the app to access and details
+      what permissions the GitHub app will have.
+8. GitHub redirects browser back to Web app, repeat _Step 6_.