Adds `Coder.StepLength`, a Vale `script` rule for [Keep steps short](https://github.com/coder/coder/blob/main/docs/.style/style-guide/procedural-writing.md#keep-steps-short). It flags an ordered-list step whose instruction, the step's first paragraph, has more than 20 words, counted as [How to count words](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#how-to-count-words) describes. Paragraphs below the instruction explain the step and aren't counted. - Severity: `warning`. - Scope: `docs/**` except `docs/.style/style-guide/**`. - Baseline: 124 findings in 60 hand-written files. The cleanup shortens each long instruction, moves its explanation into one paragraph below it, or splits a step that holds several actions. After cleanup `vale docs/` reports 0 `Coder.StepLength` findings, and the other rules report no new findings on the changed files. - The guide section now says the limit covers the instruction, and that one action or one explanation must not be broken across paragraphs to meet it. - Generated pages (`docs/reference/{api,cli,agent-api}`, `configuration-reference.md`, `prometheus.md`): no findings, so no `.vale.ini` exclusion is needed. Linear: DOCS-1272 <details><summary>Decision log</summary> **Review change (Ian's review)** - The first version limited every paragraph of a step to 20 words. The cleanup for it chopped explanations into several short paragraphs, which made steps harder to read and sometimes changed their meaning. - The rule now counts only the first paragraph segment of each step. The content files were reset to `main` and the cleanup was redone against the narrower rule. - Cleanup preferences, in order: shorten the instruction; keep a short instruction and put the explanation, with its original wording, in one paragraph below it; split a step into one step for each action; for descriptive lists (such as "How it works"), keep each item one statement. - `docs/admin/users/oidc-auth/microsoft.md` keeps the split into separate steps, with Ian's wording suggestions applied. "click" became "select" in step 16 because `Coder.SelectClick` flags it. **Rule shape** - A `script` rule (Tengo) with `scope: raw`, because the count depends on Markdown structure that per-paragraph scopes hide. - A step is an ordered-list item with a `1.` or `1)` marker. A nested ordered item is its own step. Bullets, even under a step, are not steps. - The instruction ends at a blank line, a fence, a nested list, a table row, a blockquote, block-level HTML, or an explicit hard break (`<br>`, a trailing backslash, or two trailing spaces). - Fenced code blocks, HTML comments, tables, images, and nested bullets add no words. - CRLF: `\r` counts as whitespace, and offsets come from the raw text. **Counting approximations (also in the rule header)** - A code span and a `**bold**` or `__bold__` span are one word each. - Words split on whitespace, so a hyphenated compound and `30 seconds` are one word. - Link text counts word by word, destinations are skipped, images add no words, and `<https://...>` autolinks are one word. - A token with no letter or digit, such as the `>` in `**A** > **B**`, is not a word. - Tengo indexes strings by rune but measures them in bytes, so the script rewrites each non-ASCII rune to ASCII of the same byte length first. **Tests** (fixtures under `/tmp/sltest/`, not committed; run with the repo `.vale.ini`, LF and CRLF) - Flagged: a long instruction, a short action and a long result in one paragraph, a long nested ordered step. - Not flagged: a long paragraph below a short instruction, text after a `<br>` hard break, a long paragraph after a code block, a long nested bullet. - LF and CRLF output is identical. - Pre-commit hooks (`fmt/markdown`, `lint/markdown`, `lint/emdash`, `lint/style-claims`, `lint/typos`) pass. - Not run on Windows or macOS. The rule is plain text processing, and the CRLF cases simulate Windows line endings on Linux. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.*
153 lines
6.2 KiB
Markdown
153 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.
|