GitHub Integration

The primary use case for the keymap editor supports an integration with GitHub to fetch, modify, and commit keymaps to any enabled repositories.

Terminology

• 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.

Configuration

All configuration is provided to the app via environment variables. (See The Twelve-Factor App)

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.