blob: 6d05a724e562b2b1b24587d40015847d5bd19f34 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
# 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](https://12factor.net/config))_
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_.
|
