diff options
| -rw-r--r-- | api/services/github/README.md | 80 |
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_. |