Reformats the user administration docs under `docs/admin/users` to one sentence per line, as the [docs style guide](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line) requires. Hard-wrapped paragraphs are unwrapped and lines holding several sentences are split, so a later edit to one sentence shows up as a one-line diff. Only whitespace inside paragraphs and list items changes, and the rendered pages are the same. Comparing every changed file against `main` word for word, ignoring whitespace and blockquote `>` markers, finds no differences. `git diff --word-diff` is easier to read than the line diff. Applied with an in-progress formatter, limited to pages listed in `docs/manifest.json` and excluding generated reference docs. This is one of a batch of PRs that split the docs by area (13 files changed, 362 insertions(+), 553 deletions(-)). --- 🤖 Built with AI assistance.
152 lines
6.2 KiB
Markdown
152 lines
6.2 KiB
Markdown
---
|
|
title: GitHub
|
|
---
|
|
|
|
By default, new Coder deployments use a Coder-managed GitHub app to authenticate users.
|
|
We provide it for convenience, allowing you to experiment with Coder without setting up your own GitHub OAuth app.
|
|
|
|
If you authenticate with it, you grant the control plane read access to your GitHub user email and other metadata listed during the authentication flow.
|
|
|
|
This access is necessary for the control plane to complete the authentication process.
|
|
To the best of our knowledge, Coder, the company, does not gain access to this data by administering the GitHub app.
|
|
|
|
## Default Configuration
|
|
|
|
> [!IMPORTANT]
|
|
> Installation of the default GitHub app grants Coder (the company) access to your organization's GitHub data.
|
|
>
|
|
> For production environments, we strongly recommend that you [configure your own GitHub OAuth app](#step-1-configure-the-oauth-application-in-github) to ensure that your data is not shared with Coder (the company).
|
|
|
|
To use the default configuration:
|
|
|
|
1. [Install the GitHub app](https://github.com/apps/coder/installations/select_target) in any GitHub organization that you want to use with Coder.
|
|
|
|
The default GitHub app requires [device flow](#device-flow) to authenticate.
|
|
This is enabled by default when using the default GitHub app.
|
|
If you disable device flow using `CODER_OAUTH2_GITHUB_DEVICE_FLOW=false`, it will be ignored.
|
|
|
|
1. By default, only the admin user can sign up.
|
|
To allow additional users to sign up with GitHub, add:
|
|
|
|
```sh
|
|
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
|
|
```
|
|
|
|
1. (Optional) If you want to limit sign-ups to specific GitHub organizations, set:
|
|
|
|
```sh
|
|
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
|
|
```
|
|
|
|
## Disable the Default GitHub App
|
|
|
|
You can disable the default GitHub app by [configuring your own app](#step-1-configure-the-oauth-application-in-github) or by adding the following environment variable to your [control plane configuration](../../reference/cli/server/index.md#options):
|
|
|
|
```sh
|
|
CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE=false
|
|
```
|
|
|
|
> [!NOTE]
|
|
> After you disable the default GitHub provider, the **Sign in with GitHub** button might still appear on your login page even though the authentication flow is disabled.
|
|
>
|
|
> To completely hide the GitHub sign-in button, you must disable the default provider and ensure you don't have a custom GitHub OAuth app configured.
|
|
|
|
## Step 1: Configure the OAuth application in GitHub
|
|
|
|
1. [Register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
|
|
|
|
1. GitHub will ask you for the following Coder parameters:
|
|
|
|
- **Homepage URL**:
|
|
Set to your Coder deployment's [`CODER_ACCESS_URL`](../../reference/cli/server/index.md#--access-url) (e.g. `https://coder.domain.com`)
|
|
- **User Authorization Callback URL**:
|
|
Set to `https://coder.domain.com`
|
|
|
|
If you want to allow multiple Coder deployments hosted on subdomains, such as `coder1.domain.com`, `coder2.domain.com`, to authenticate with the same GitHub OAuth app, then you can set **User Authorization Callback URL** to the `https://domain.com`
|
|
|
|
1. Take note of the Client ID and Client Secret generated by GitHub.
|
|
You will use these values in the next step.
|
|
|
|
1. Coder needs permission to access user email addresses.
|
|
|
|
Find the **Account Permissions** settings for your app and select **read-only** for **Email addresses**.
|
|
|
|
## Step 2: Configure Coder with the OAuth credentials
|
|
|
|
The control plane reads these settings from environment variables.
|
|
Set them wherever your deployment manages environment variables.
|
|
For example, use Helm `values.yaml` for Kubernetes or `/etc/coder.d/coder.env` for a system service.
|
|
|
|
**Kubernetes (Helm):**
|
|
set the variables under `coder.env` in your `values.yaml`:
|
|
|
|
```yaml
|
|
coder:
|
|
env:
|
|
- name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
|
|
value: "true"
|
|
- name: CODER_OAUTH2_GITHUB_CLIENT_ID
|
|
value: "533...des"
|
|
- name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
|
|
value: "G0CSP...7qSM"
|
|
# If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
|
|
- name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
|
|
value: "your-org"
|
|
# If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and its value
|
|
#- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
|
|
# value: "true"
|
|
```
|
|
|
|
Then apply the change with `helm upgrade`:
|
|
|
|
```sh
|
|
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
|
|
```
|
|
|
|
**System service:**
|
|
add the variables to `/etc/coder.d/coder.env`:
|
|
|
|
```sh
|
|
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
|
|
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
|
|
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
|
|
CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
|
|
```
|
|
|
|
Then restart Coder with `sudo service coder restart`.
|
|
|
|
> [!TIP]
|
|
> To allow everyone to sign up using GitHub, set:
|
|
>
|
|
> ```shell
|
|
> CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
|
|
> ```
|
|
|
|
For GitHub Enterprise support, also set `CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL`.
|
|
|
|
> [!NOTE]
|
|
> Every option above also has an equivalent CLI flag (for example, `CODER_OAUTH2_GITHUB_CLIENT_ID` becomes `--oauth2-github-client-id`).
|
|
> CLI flags are convenient for ad-hoc invocations of `coder server` during local development.
|
|
> For production deployments, prefer environment variables so the configuration lives with the container, Helm chart, or service unit that manages Coder.
|
|
> See the [configuration reference](../setup/configuration-reference.md) for the full mapping between environment variables and flags.
|
|
|
|
We recommend requiring and auditing MFA usage for all users in your GitHub organizations.
|
|
This can be enforced from the organization settings page in the **Authentication security** sidebar tab.
|
|
|
|
## Device Flow
|
|
|
|
Coder supports [device flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow) for GitHub OAuth.
|
|
This is enabled by default for the default GitHub app and cannot be disabled for that app.
|
|
|
|
For your own custom GitHub OAuth app, you can enable device flow by setting:
|
|
|
|
```sh
|
|
CODER_OAUTH2_GITHUB_DEVICE_FLOW=true
|
|
```
|
|
|
|
Device flow is optional for custom GitHub OAuth apps.
|
|
We generally recommend using the standard OAuth flow instead, as it is more convenient for end users.
|
|
|
|
> [!NOTE]
|
|
> If you're using the default GitHub app, device flow is always enabled regardless of the `CODER_OAUTH2_GITHUB_DEVICE_FLOW` setting.
|