|
1 | 1 | # GitHub |
2 | 2 |
|
3 | | -## Default Configuration |
4 | | - |
5 | 3 | By default, new Coder deployments use a Coder-managed GitHub app to authenticate |
6 | | -users. We provide it for convenience, allowing you to experiment with Coder |
7 | | -without setting up your own GitHub OAuth app. Once you authenticate with it, you |
8 | | -grant Coder server read access to your GitHub user email and other metadata listed |
9 | | -during the authentication flow. |
| 4 | +users. |
| 5 | +We provide it for convenience, allowing you to experiment with Coder |
| 6 | +without setting up your own GitHub OAuth app. |
| 7 | + |
| 8 | +If you authenticate with it, you grant Coder server read access to your GitHub |
| 9 | +user email and other metadata listed during the authentication flow. |
10 | 10 |
|
11 | 11 | This access is necessary for the Coder server to complete the authentication |
12 | | -process. To the best of our knowledge, Coder, the company, does not gain access |
| 12 | +process. |
| 13 | +To the best of our knowledge, Coder, the company, does not gain access |
13 | 14 | to this data by administering the GitHub app. |
14 | 15 |
|
| 16 | +## Default Configuration |
| 17 | + |
15 | 18 | > [!IMPORTANT] |
16 | 19 | > The default GitHub app requires [device flow](#device-flow) to authenticate. |
17 | | -> This is enabled by default when using the default GitHub app. If you disable |
18 | | -> device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored. |
| 20 | +> |
| 21 | +> This is enabled by default when using the default GitHub app. |
| 22 | +> If you disable device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored. |
19 | 23 |
|
20 | | -By default, only the admin user can sign up. To allow additional users to sign |
21 | | -up with GitHub, add the following environment variable: |
| 24 | +By default, only the admin user can sign up. |
| 25 | +To allow additional users to sign up with GitHub, add the following environment variable: |
22 | 26 |
|
23 | 27 | ```env |
24 | 28 | CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true |
25 | 29 | ``` |
26 | 30 |
|
27 | 31 | [Install the GitHub app](https://github.com/apps/coder/installations/select_target) in every GitHub organization that you need to limit sign ups to. |
28 | | -**This will grant Coder, the company, access to your organizations' data as |
29 | | -described in the installation flow.** In a production environment, we recommend |
30 | | -configuring your own GitHub OAuth app as outlined further below, so all of your |
31 | | -data is kept private. |
| 32 | +This will grant Coder, the company, access to your organizations' data as described in the installation flow. |
| 33 | +In a production environment, we recommend configuring your own GitHub OAuth app as outlined further below, so all of your data is kept private. |
32 | 34 |
|
33 | 35 | If you'd like to proceed with the default GitHub app, install it in the |
34 | 36 | organizations you want to limit sign ups to by visiting |
@@ -135,23 +137,24 @@ To upgrade Coder, run: |
135 | 137 | helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml |
136 | 138 | ``` |
137 | 139 |
|
138 | | -We recommend requiring and auditing MFA usage for all users in your GitHub |
139 | | -organizations. This can be enforced from the organization settings page in the |
140 | | -"Authentication security" sidebar tab. |
| 140 | +We recommend requiring and auditing MFA usage for all users in your GitHub organizations. |
| 141 | +This can be enforced from the organization settings page in the **Authentication security** sidebar tab. |
141 | 142 |
|
142 | 143 | ## Device Flow |
143 | 144 |
|
144 | 145 | Coder supports |
145 | 146 | [device flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow) |
146 | | -for GitHub OAuth. This is enabled by default for the default GitHub app and cannot be disabled |
147 | | -for that app. For your own custom GitHub OAuth app, you can enable device flow by setting: |
| 147 | +for GitHub OAuth. |
| 148 | +This is enabled by default for the default GitHub app and cannot be disabled for that app. |
| 149 | + |
| 150 | +For your own custom GitHub OAuth app, you can enable device flow by setting: |
148 | 151 |
|
149 | 152 | ```env |
150 | 153 | CODER_OAUTH2_GITHUB_DEVICE_FLOW=true |
151 | 154 | ``` |
152 | 155 |
|
153 | | -Device flow is optional for custom GitHub OAuth apps. We generally recommend using |
154 | | -the standard OAuth flow instead, as it is more convenient for end users. |
| 156 | +Device flow is optional for custom GitHub OAuth apps. |
| 157 | +We generally recommend using the standard OAuth flow instead, as it is more convenient for end users. |
155 | 158 |
|
156 | 159 | > [!NOTE] |
157 | 160 | > If you're using the default GitHub app, device flow is always enabled regardless of |
|
0 commit comments