Builds on #30782, which is merged; the branch now merges `main`. Adds `Coder.LatinAbbreviations`, a Vale rule that enforces [Latin abbreviations](https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#latin-abbreviations). - Suggests "for example", "that is", and "and so on" for `e.g.`, `i.e.`, and `etc.`, including `eg.`, `ie.`, and a missing final period (`e.g`). - Severity: `suggestion`. Scope: `docs/**` except `docs/.style/style-guide/**`, limited to paragraphs, lists, headings, and blockquotes. Table cells and code are skipped. - Baseline: 170 findings in 91 files. The brief estimated 148. - Cleanup: 153 findings fixed across 81 hand-written pages, 0 left in linted pages. The count is lower than the original 158 because other PRs on `main` already rewrote or removed some of the lines, and `parameters.md` was deleted on `main`. - `vs.` and `et al.` aren't flagged. Commits: 1. `docs(docs): use English forms of Latin abbreviations` 2. `feat(docs/.style): enable Coder.LatinAbbreviations Vale rule` Generated pages: `.vale.ini` skips `docs/reference/{api,cli}/*.md` and `docs/admin/setup/configuration-reference.md` for this rule, as it does for `Coder.UnitSpacing`. Their prose comes from CLI flag help text and Swagger comments in Go source, and `make gen` rewrites them, so a hand edit fails the `gen` check (an earlier revision of this PR edited `configuration-reference.md` and failed `gen` for that reason). Cleaning them means editing Go and regenerating the help golden files and API docs, which is left for a follow-up. Linear: DOCS-450 <details> <summary>Decision log</summary> - `extends: substitution`, so the message names the replacement: "Consider 'for example' instead of 'e.g.'". - `scope: [paragraph, list, heading, blockquote]`. The single scope `paragraph` skips list items, blockquotes, and headings, so all four are listed. Table cells have their own scope and stay excluded. - Explicit `[Ee]` and `[Ii]` classes with `ignorecase: false`, so sentence-initial `E.g.,` still matches but the browser name `IE.` doesn't. - `eg.` and `ie.` require the trailing period so ordinary words and file extensions stay quiet. - Cleanup rules, applied by script and then reviewed line by line: - `e.g.` and `i.e.` become "for example," and "that is," (capitalized at the start of a sentence), with a comma added when the original had none. - `etc.` becomes "and so on", with the sentence-ending period kept when `etc.` closed the sentence. - Lines inside table rows, fenced blocks, and code spans are untouched, so are the style guide and the generated pages. - Hard-wrapped lines keep their wrapping, and CRLF files keep CRLF. - The rest of the Vale output is unchanged: the per-rule counts for every other rule match the pre-cleanup run. Test cases (fixtures under `/tmp/latin-test/`, not committed), run with LF and CRLF line endings: - Flagged (15 each): `e.g.,` in a paragraph, `i.e.,`, `etc.` at the end of a sentence and before a comma, `eg.`, `ie.`, `e.g` and `i.e` without the final period, `E.g.,`, `I.e.,`, `Etc.`, a blockquote, a list item, a numbered item, and a heading. - Not flagged: a table row with `e.g.,`, `i.e.,`, and `etc.`, code spans, a fenced block, "for example", "that is", "and so on", `IE.`, `genre`, `series`, `egg`, `tie`, `etcetera`, `vs.`, `et al.`. - Known edge case: a path-like token such as `path/i.e/x` outside code matches. It doesn't occur in the corpus. Checks: - `vale --output=line docs/`: 0 `Coder.LatinAbbreviations` findings. - `go run ./scripts/styleclaims` passes. - The pre-commit-light hook passes on both commits. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.*
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) (for example, `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.
|