Normalizes the three overlapping names for the thing that serves the Coder API and dashboard. This is step 1 of the Install/Deploy and Administration refactor ([DOCS-685](https://linear.app/codercom/issue/DOCS-685), [DOCS-738](https://linear.app/codercom/issue/DOCS-738)) and lands first because every later page depends on settled terminology. Resolves [DOCS-871](https://linear.app/codercom/issue/DOCS-871). ## The rule | Term | Means | Use when | |---|---|---| | control plane | The component that serves the Coder API and dashboard, brokers connections, and coordinates provisioners | Default in prose, diagrams, planning, sizing, security | | `coderd` | The process that implements it | Architecture internals, metrics, logs, flags, troubleshooting | | `coder server` | The literal CLI command | Only when the reader will type it | Retired: "the Coder server" as a name for the component, and "a service" as a standalone description of it. ## What changed - **`docs/.style/style-guide/word-choice.md`**: new "Naming Coder's components" rule, with do/don't examples. Also fixes a "Do" example on that page that itself used "the Coder server". - **`docs/reference/glossary.md`**: rewrote `coderd` and Control plane, added a `coder server` entry. The existing Control plane entry defined it as "the collective term for `coderd`, its provisioners, and its database", which made it indistinguishable from the Deployment entry two sections later. Control plane is now the component; Deployment remains the whole installation. - **65 pages** across `docs/admin`, `docs/install`, `docs/get-started`, `docs/tutorials`, `docs/user-guides`, `docs/ai-coder`, and `docs/about`: roughly 154 component-sense "Coder server" usages, 21 bare "the server" usages meaning the control plane, 3 "a service" descriptions, and 43 unbackticked `coderd` mentions in prose. - One real bug caught in passing: `docs/tutorials/best-practices/security-best-practices.md` documented `coderd server --disable-path-apps`, which is not a command. Now `coder server`. Generated files were not touched: `configuration-reference.md`, `prometheus.md`, `audit-logs.md`, `reference/cli/*`, `reference/api/*`, and the generated blocks inside `feature-stages.md`. Those still contain the retired term and need generator-side changes; see the deferred list below. ## Reviewer attention, please **Anchor changes.** 11 headings were renamed, so their fragments change. No in-repo link targets any of them (the one internal link that did was updated), but external deep links from tickets or blog posts would break, and fragments cannot be fixed with a redirect. Happy to revert any of these if you would rather they ride along with the page moves in [DOCS-869](https://linear.app/codercom/issue/DOCS-869), which changes those URLs anyway. <details> <summary>Renamed headings and their old fragments</summary> | File | Old fragment | New heading | |---|---|---| | `admin/networking/index.md` | `#coder-server` | `## Control plane` | | `install/index.md` | `#starting-the-coder-server` | `## Starting the control plane` | | `install/uninstall.md` | `#the-coder-server-binary-and-cli` | `## The Coder binary and CLI` | | `install/registry-mirror-artifactory.md` | `#step-5-configure-coder-server-or-provisioners` | `## Step 5: Configure the control plane or provisioners` | | `install/cloud/compute-engine.md` | `#configuring-coder-server` | `## Configuring the control plane` | | `get-started/index.md` | `#cant-start-coder-server-address-already-in-use` | ``### Can't start `coder server`: Address already in use`` | | `tutorials/external-database.md` | `#coder-server-fails-startup-with-...` | ``### `coder server` fails startup with ...`` | | `tutorials/faqs.md` | `#how-do-i-change-the-access-url-for-my-coder-server` | `## How do I change the access URL for my control plane?` | | `tutorials/best-practices/security-best-practices.md` | `#coder-server` | `## Control plane` | | `tutorials/best-practices/security-best-practices.md` | `#server-logs-and-audit-logs` | `### Control plane logs and audit logs` | | `tutorials/best-practices/scale-coder.md` | `#coder-server`, `#how-to-capture-coder-server-metrics-with-prometheus` | `## Control plane`, `### How to capture control plane metrics with Prometheus` | </details> **One deliberate deviation from the issue.** DOCS-871 proposed reserving "sub-agent" for the Coder Agents sense and using "devcontainer agent" for the workspace sense. I did not make that change. The glossary already disambiguates with "Sub-agent (Coder Agents)" and "Sub-agent (dev containers)", and "devcontainer agent" would violate the existing dev container spelling rule in the same style guide, which requires "dev container" as two lowercase words. The current split reads correctly and costs no churn. Happy to revisit if you disagree. <details> <summary>Deferred, with reasons</summary> - **Generated content still says "Coder server".** `reference/cli/*` comes from Go command help text, `configuration-reference.md` from `configdocgen`, and `reference/api/*` from Swagger annotations. Fixing those means changing Go source, which belongs in its own PR so a docs review does not turn into a backend review. - **`validated-architectures/index.md` "also known as `coderd`"** is fixed here, but the page's larger problem is that it holds four documents in one file. That split is [DOCS-868](https://linear.app/codercom/issue/DOCS-868). - **"server flag" phrasing** in `admin/users/idp-sync.md` and `admin/users/oidc-auth/index.md` means `coder server` flags. Left alone; rewording those sentences is a copy edit, not a substitution. - **Metric and UI labels** such as "Dashboard-to-server latency" in `admin/networking/index.md`. Renaming risks diverging from what the dashboard shows. - **Pre-existing `Coder.GerundHeading` warnings** on headings this PR touches, and a "from from" typo in `scale-coder.md`. Out of scope for a terminology pass. - **Peer-sense "server"** in NAT traversal prose, where "client or server" describes the connection roles rather than the control plane. Needs restructuring, not substitution. </details> ## Verification | Check | Result | |---|---| | `make lint/emdash` | pass | | `make lint/markdown` | pass, 504 files, 0 errors | | `make lint/docs-html` | pass | | `make lint/prose` | pass, findings identical to the `main` baseline (1 intentional demo error, 145 warnings, 1 suggestion; only Vale's file ordering and one line-number shift in `glossary.md` differ) | | `make gen` | clean, no drift | | `make fmt/markdown` | applied | No redirects needed: no page moved or was renamed in this PR. <details> <summary>Merged main, 2026-09-14</summary> One conflict, in `docs/ai-coder/ai-gateway/providers.md`. Both hunks were text this PR had edited and `main` had since deleted in #29053, which removed env-based AI provider configuration: - The deprecated provider seeding note, which held a `coderd` backtick fix, is gone. Took `main`. - The failure-mode table lost its env-drift row. Took `main`'s two rows and reapplied the `coderd` logs wording. `main` also landed new prose carrying the retired terms, so the pass was extended to cover it: - `docs/admin/integrations/oauth2-provider.md`: two "the server log(s)" in the scope-enforcement sections added by #29144 are now "the `coderd` log(s)"; "a `scope` the server will not grant" is now "the control plane". - `docs/reference/cli/index.md` gained "the server" from #29104, and stays deferred as generated content. The new `docs/ai-coder/agent-relay/claude-code.md` needed no change, and no page `main` added links to a heading this PR renamed. </details> <details> <summary>Decision log for the wider refactor</summary> Agreed with @nickvigilante before implementation, recorded on DOCS-685 and in the Notion outline: 1. Feature stages and release channels move to Reference; ESR upgrade guides move under Operate. No new top-level Releases section. 2. `data-retention.md` moves to Administration > Security; `chat-lifecycle-hooks.md` moves into the Coder Agents docs. `admin/setup/` therefore survives as "Deployment configuration" and `configdocgen` is not touched. 3. Prepare is advisory, not a gate, framed as "don't know where to start? Start here", with lead times and owners per item. 4. One actor table, on the Install overview, spanning all five phases, noting that one person can be several actors and several people can be one actor. 5. The quickstart stays independent and is mentioned once, on the Install overview. The proposed `server/single-machine` page is dropped. 6. Coder Validated Architecture keeps its name in nav, defined in-page, with a glossary entry. 7. PR 3 is split: moves only, then prose, so the riskiest change reads as a pure rename diff. 8. For every PR that moves a page, the coder.com `redirects.json` change merges first. 9. There is no Download section and no CLI page in docs. Per-OS CLI steps live on coder.com/download and the Install overview links to it. </details> Generated with Coder Agents on behalf of @nickvigilante.
174 lines
6.2 KiB
Markdown
174 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.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.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.
|