## Summary Addresses 106 of the 113 conflicts between the docs and the code that the November audit of `main` found: 102 are fixed and 4 have an interim docs fix. Every finding was re-checked against the code before it was fixed. Most fixes are docs-only. Three are small code fixes where the docs described the intended behavior and the code was wrong, each in its own commits so it can be split out. No change in this PR alters template build or agent behavior. ## Changes Fixes by area (finding counts): templates 28, install 13, integrations and monitoring 13, auth and security 12, networking 11, Coder Agents 9, AI governance 7, reference 7, workspaces 6. Code fixes. Each needs a look from the code owner. If an owner prefers not to take one, drop its commits and I will change the docs to describe the current behavior instead. | Commits | Change | Risk to check | |---------|--------|---------------| | `fix: keep built-in listener defaults in packaged coder.env`, and three follow-up commits | `coder.env` comments out `CODER_HTTP_ADDRESS=` and the three `CODER_TLS_*` lines, so an untouched package install listens on `127.0.0.1:3000` as the docs say. Only the `CODER_HTTP_ADDRESS=` line changed behavior. The TLS options default to empty, so commenting them out is for consistency. The Lima examples rewrite the commented line and fail if the line is not found. A test compares every option that the file sets against the built-in defaults. | The deb and RPM packages were not built or installed. Every released package through v2.39.0 ships the empty line, and upgrades keep an existing file (`config\|noreplace`), so the upgrade pages now say how to fix it. | | `fix(cli/clilog): accept log sinks that are all disabled`, and three follow-up commits | `--log-human=/dev/null` with no other log location no longer fails with "no loggers provided". It is the documented way to disable logging. An empty location still fails with that error when no other sink is set, as before. | Behavior change: with `/dev/null`, the server and the provisioner daemon can start with no log output. | | `fix(cli): detect CODER_PROC_PRIO_MGMT by presence`, and a comment follow-up | Log line only. With the variable set to an empty value, the agent now logs that process priority management is enabled, which is what `agentexec` already does. No detection or behavior change. | Low. | Two option descriptions in `codersdk/deployment.go` are corrected, with the CLI reference, configuration reference, and golden files regenerated: the default quiet hours schedule (the max deadline is the quiet hours window on the next day that the template's autostop requirement applies) and `--experiments` (`*` opts in to the experiments marked safe, also in `enterprise/cli/provisionerdaemonstart.go`). ### Code fixes that were reverted after review Two code fixes from the first version of this PR are reverted in the branch. The net diff has no change under `agent/` or `coderd/`. The docs now describe what the code does, and both issues stay open for the owner. - **`error` merge strategy for `coder_env` (DOCS-1669).** The fix made `merge_strategy = "error"` fail whenever a name was set twice, whatever the resource order. Existing template versions that pair an `error` entry with a later `replace` or `append` entry would start to fail every build after `terraform apply`. That is a breaking change that needs its own PR and release note. The fix and its tests are in `dff8e7c6ce` and can be cherry-picked. `environment-variables.md` now says the check runs only when the `error` resource is processed. - **Nice value before the capability drop (DOCS-1687).** The fix let `coder agent-exec` apply a negative nice value by calling `setpriority` before it drops effective capabilities. The current order is deliberate: with the fix, any local process could run the agent binary with `--coder-nice=-20` when the binary has the `CAP_SYS_NICE` file capability. `process-priority.md` now says a nice value below the agent's own is not applied, and no longer tells admins to grant `CAP_SYS_NICE`. ## Not included Seven findings are left out. - DOCS-1629: covered by #31639. - DOCS-1703 and DOCS-1724: covered by #31980. - DOCS-1584, DOCS-1683, DOCS-1685, DOCS-1686: each needs an owner decision, and no neutral docs wording exists until that decision is made. The validation comment on each issue names the decision. Four fixes are interim, so their issues stay open: - DOCS-1600: the AI Gateway pages now agree that the legacy metric names are deprecated and "will be removed in a future release". The code still emits them, and its TODO names v2.37, which has shipped. The owner still needs to set the removal release. - DOCS-1689: the page now says **New Template** opens the builder only for users with the Owner role, because the page gates on read access to the deployment config. Whether Template Admins should get the builder is still open. - DOCS-1669 and DOCS-1687: docs-only for now. Refer to [Code fixes that were reverted after review](#code-fixes-that-were-reverted-after-review). ## Review notes - Claims that describe product intent and need an owner's yes: the Premium qualifier on per-organization workspace sharing (the API route has no license check, the dashboard needs multiple organizations), `organization` port sharing in OSS, the telemetry field list, and the `1-5` cron range in the prebuilds schedule example. - Not run end to end: the PostgreSQL TLS procedure on a cluster, the OpenShift and air-gapped examples, the BSD `date` and `tar` forms on macOS, the Windows command on the multiple Kubernetes clusters page, and the keep-alive script in `docs/reference/index.md` (only its comparison logic was run, against sample values). Nothing was checked on a live deployment. - Likely merge conflicts with open PRs: #31990 (`mcp-server.md`, `feature-stages.md`, `docker-in-workspaces.md`), #31982 (`workspace-management.md`), #31980 (`health-check.md`), #31977 (`manage-provisioner-jobs.md`), #31869 (`airgap.md`), #30486 (`add-envbuilder.md`), and #31326 and #31531 (`codersdk/deployment.go` and generated files). ## Testing - `make pre-commit` (gen, fmt, lint, slim build), before the PR opened and again after the review changes. - `go test` for `./cli/clilog/...`, `./codersdk/`, `./cli/` (`TestServer`, `TestAgent`, and golden files), and `./enterprise/cli/` (provisioner, server, and help golden files). `./agent/agentexec/...` and `./coderd/provisionerdserver/...` pass after the reverts. Linux only. CI covers macOS and Windows. - The `coder.env` test fails against the file on `main` and passes against the new one. It reads the file with `godotenv`, which accepts CRLF line endings. - An empty `CODER_HTTP_ADDRESS=` was confirmed end to end with a full build of the server (output below). - The new `sed` and `grep` lines in the Lima examples were run with GNU tools against the old and the new form of `coder.env`. The Lima VMs were not started. - `--log-human=/dev/null` and `CODER_LOGGING_HUMAN=` were confirmed with the same build (output below). - `coder agent-exec --coder-nice=-5 -- echo` from a full build, as a non-root user: `coder-agent: failed to adjust niceness to -5 ...: permission denied` on stderr, the command output on stdout, exit code 0. - `postgres-ssl.md` rendered with the GitHub Markdown API: two ordered lists with three and five items, where `main` has six lists. - markdownlint, the table formatter, `make lint/emdash`, `make lint/docs-html`, `make lint/docs-manifest`, `make lint/docs-redirects`, `make lint/style-claims`, and Vale on the changed lines. - A doc-check self-review of the docs diff by four independent reviewers. It found six problems, which are fixed. The accuracy and coverage lenses ran on every area. The language and structure lenses ran in full on only part of the diff. <details> <summary>Test and terminal output for the code fixes (Linux)</summary> ```console $ go test ./codersdk/ -run TestPackagedCoderEnvKeepsDefaults -count=1 -v --- PASS: TestPackagedCoderEnvKeepsDefaults (0.00s) ok github.com/coder/coder/v2/codersdk 0.071s $ go test ./cli/clilog/ -run TestBuilder -count=1 -v --- PASS: TestBuilder (0.00s) --- PASS: TestBuilder/NoSinks (0.00s) --- PASS: TestBuilder/NoSinks/JSONDevNull (0.00s) --- PASS: TestBuilder/NoSinks/StackdriverDevNull (0.00s) --- PASS: TestBuilder/NoSinks/NoConfiguration (0.00s) --- PASS: TestBuilder/NoSinks/HumanDevNull (0.00s) --- PASS: TestBuilder/WithHuman (0.00s) --- PASS: TestBuilder/WithFilter (0.00s) --- PASS: TestBuilder/WithJSON (0.00s) --- PASS: TestBuilder/Verbose (0.00s) --- PASS: TestBuilder/FromDeploymentValues (0.01s) --- PASS: TestBuilder/FromDeploymentValues/Defaults (0.00s) --- PASS: TestBuilder/FromDeploymentValues/EmptyHumanEnv (0.00s) --- PASS: TestBuilder/FromDeploymentValues/Override (0.00s) ok github.com/coder/coder/v2/cli/clilog 0.171s $ TMPDIR=$HOME/.cache/agentexec-tmp go test ./agent/agentexec/... ./coderd/provisionerdserver/... -count=1 ok github.com/coder/coder/v2/agent/agentexec 4.236s ok github.com/coder/coder/v2/coderd/provisionerdserver 2.404s # Full build of the server (go build ./cmd/coder). An empty value stops it before it connects to the database. $ CODER_HTTP_ADDRESS= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: TLS is disabled. Enable with --tls-enable or specify a HTTP address # With the variable unset, the server passes that check and goes on to the database. $ coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' 2026-11-13 02:19:41.901 [warn] ping postgres: retrying error="dial tcp 127.0.0.1:1: connect: connection refused" try=11 Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused # An empty log location with no other sink still stops the server. $ CODER_LOGGING_HUMAN= coder server --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: make logger: no loggers provided, use /dev/null to disable logging # /dev/null passes the logger check. The server prints no log lines and goes on to the database. $ coder server --log-human=/dev/null --postgres-url 'postgres://127.0.0.1:1/x?sslmode=disable' Encountered an error running "coder server", see "coder server --help" for more information error: connect to postgres: connect to postgres: unable to connect after 11 tries; last error: dial tcp 127.0.0.1:1: connect: connection refused ``` </details> ## Linear Fixes DOCS-1583, DOCS-1585, DOCS-1586, DOCS-1587, DOCS-1588, DOCS-1589, DOCS-1590, DOCS-1591, DOCS-1592, DOCS-1593, DOCS-1594, DOCS-1595, DOCS-1596, DOCS-1597, DOCS-1598, DOCS-1599, DOCS-1601, DOCS-1602, DOCS-1603, DOCS-1604, DOCS-1605, DOCS-1606, DOCS-1607, DOCS-1608, DOCS-1609, DOCS-1614, DOCS-1618, DOCS-1619, DOCS-1620, DOCS-1624, DOCS-1635, DOCS-1639, DOCS-1644, DOCS-1651, DOCS-1652, DOCS-1653, DOCS-1654, DOCS-1655, DOCS-1656, DOCS-1657, DOCS-1658, DOCS-1659, DOCS-1660, DOCS-1661, DOCS-1662, DOCS-1663, DOCS-1664, DOCS-1665, DOCS-1666, DOCS-1667, DOCS-1668, DOCS-1670, DOCS-1671, DOCS-1672, DOCS-1673, DOCS-1674, DOCS-1675, DOCS-1676, DOCS-1677, DOCS-1678, DOCS-1679, DOCS-1680, DOCS-1681, DOCS-1682, DOCS-1684, DOCS-1688, DOCS-1690, DOCS-1691, DOCS-1692, DOCS-1693, DOCS-1694, DOCS-1695, DOCS-1696, DOCS-1697, DOCS-1698, DOCS-1699, DOCS-1700, DOCS-1701, DOCS-1702, DOCS-1704, DOCS-1705, DOCS-1706, DOCS-1707, DOCS-1708, DOCS-1709, DOCS-1710, DOCS-1711, DOCS-1712, DOCS-1713, DOCS-1714, DOCS-1715, DOCS-1716, DOCS-1717, DOCS-1718, DOCS-1719, DOCS-1720, DOCS-1721, DOCS-1722, DOCS-1723, DOCS-1725, DOCS-1726, DOCS-1727 Part of DOCS-1600, DOCS-1689, DOCS-1669, DOCS-1687 <details> <summary>Decision log</summary> ### Scope - One PR for all findings, as agreed with the reviewer. The code fixes are separate commits so an owner can ask for any of them to move to its own PR. Nothing in the PR is a breaking change, so the title has no `!`. - A finding was skipped only when an open PR already covers it, or when every available wording would assert an undecided product behavior. - Each validation comment on the Linear issues records the evidence, the corrections to the original finding, and what was not verified. ### Docs or code - The default was a docs-only fix that describes what the code does. - A code fix was chosen when the docs describe a behavior the code plainly intended and the code change is small and testable: the packaged env file, the log sink check, and the log line for the environment variable presence check. - The `error` merge strategy and the nice value ordering started as code fixes and went back to docs-only after review. The first breaks existing template versions. The second weakens a deliberate security ordering. - The SCIM `userName` finding (DOCS-1609) took the docs path. The handler is unchanged. ### Wording choices worth a second look - `feature-stages.md` says `--experiments=*` enables only the experiments marked safe, and points to the "Get safe experiments" API. It does not list the other experiments, because the list would drift and those experiments are hidden on purpose. The `--experiments` flag help now says the same. - `agent-metadata.md` replaces the writes-per-second formula with a description of the batcher (each server replica writes one statement every 5 seconds, or sooner at 500 entries). - `extending-templates/index.md` no longer calls `startup_script` deprecated. The provider documents it as an alias for a `coder_script`. - `postgres-ssl.md` separates client verification from server verification, so the server verification steps work alone. - `rpm.md`, `upgrade.md`, and the 2.29 to 2.34 ESR upgrade page explain the empty `CODER_HTTP_ADDRESS=` line that older packages shipped, because upgrades keep the old file. The behavior changed in v2.34.0 with the serpent upgrade in #24926. - The keep-alive script in `docs/reference/index.md` reads the current deadline and skips the request when it is already later. The comparison is on text, so it applies only when the API returns a UTC timestamp, which needs the database to use the UTC time zone. Otherwise the script sets the deadline on every pass, as it did before, and the page says so. - `external-auth.md` anchors the new GitHub Enterprise regex example. The older unanchored examples on that page and on `git-providers.md` are not changed here. ### Self-review findings that were rejected - "The builder opens for Template Admins": the Templates page needs a successful deployment config read, which the Template Admin role does not have. - "Organization Admins can set AI model prices": the price write authorizes against a site-level object, which organization-scoped grants do not match. - "The provisioner chart sets no default resources": `helm/libcoder/templates/_coder.yaml` applies 2000m and 4096Mi when `coder.resources` is empty. ### Automated review, round 1 The `coder-agents-review` app left 45 findings on `8853332`. Fixed: the two reverts above, the anchored regex, the `coder.env` follow-ups (Lima examples, upgrade notes, a comment in the file, and a test that covers every option in the file), the clilog change, the two option descriptions, and the docs findings (CORS behavior, token lifetime example, keep-alive script, agent metadata, refresh token errors, `switch` form type, `dbcrypt` skip list, and a stray line in a YAML example). Declined, with the reason on each thread: - Refactoring the `agentexec` logging and renaming its log field: not related to a docs conflict. - Rewording the "process priority management not enabled (linux-only)" log message: the docs quote the message, and the wording predates this PR. - Problems in code and docs that this PR does not change (the `Capabilities` subtest, the Helm values comment, the AWS provider path in `airgap.md`, and others in the review's out-of-scope list). ### Automated review, round 2 The app left 14 new findings on `04925bd`, and accepted the three declined threads on `cli/agent.go`. All 14 are fixed. The main one: the round 1 change that removed the "no loggers provided" error went too far, because an empty log location would then start a server with no logs. The error is back for every case except `/dev/null`. Reported by the app as out of scope and not changed: the swagger annotation for `GET /api/v2/experiments/available` declares an array, but the handler returns an object with a `safe` array. Three Storybook fixtures keep the old `--experiments` description. ### Automated review, round 3 The app confirmed that all round 2 findings are fixed, and left 10 small findings on `f55cb6d` (8 P4, 2 Nit). All are fixed: the TLS condition and the release range in the `coder.env` notes, one place for the `/dev/null` rule in `clilog`, two test cases, a clearer test failure, and the CPU example in `agent-metadata.md`. ### Automated review, rounds 4 and 5 Round 4 left one P4 on `8fffb38` (name the `--trace` option in the logging note), which is fixed. Round 5 on `2ce754e` reports no new findings and says every earlier finding is fixed or closed. The app did not post an approval: it leaves its out-of-scope items and the code fixes to a human reviewer. Two threads on `cli/agent.go` stay open on purpose for the code owner. ### Doc-check review The doc-check workflow left 12 comments on `2ce754e` (10 blocking, 2 suggestions). All are fixed in `c888885`: "refer to" or "visit" in place of "see" for cross-references on the lines this PR added, the **New template** label as the dashboard shows it, one instruction per step in the server verification procedure of `postgres-ssl.md`, and two wording changes in `process-priority.md`. The `CAP_SYS_NICE` sentence keeps a short reason, which differs from the suggested text. The `coder-agents-review` app then reviewed that commit (rounds 6 and 7). Round 6 left two P4 findings, fixed in `30b2c79`: the `failed to adjust niceness` message is described once, in the troubleshooting entry, with where it appears, and the client verification steps in `postgres-ssl.md` render as one numbered list. Round 7 reports no new findings. `2a6035c` then softens one sentence from that fix, because the agent logs the stderr of devcontainer CLI commands. The app was not run again on that commit. ### Adjacent gaps found and not fixed here - `add-envbuilder.md` has the same `zip` command that `template-from-scratch.md` had. - `template-from-scratch.md` leaves the reader in `build/` after `cd $_`, before a step that runs from `template-tour`. </details> --- _Generated by Coder Agents on behalf of @nickvigilante._ --------- Co-authored-by: Ben Potter <me@bpmct.net>
19 KiB
title
| title |
|---|
| External authentication |
Coder supports external authentication via OAuth2.0. This allows enabling any OAuth provider as well as integrations with Git providers, such as GitHub, GitLab, and Bitbucket.
External authentication can also be used to integrate with external services like JFrog Artifactory and others.
To add an external authentication provider, you'll need to create an OAuth application. The following providers have been tested and work with Coder:
If you have experience with a provider that is not listed here, file an issue
Configuration
Set environment variables
After you create an OAuth application, set environment variables to configure the control plane to use it:
CODER_EXTERNAL_AUTH_0_ID="<USER_DEFINED_ID>"
CODER_EXTERNAL_AUTH_0_TYPE=<github|gitlab|azure-devops|bitbucket-cloud|bitbucket-server|etc>
CODER_EXTERNAL_AUTH_0_CLIENT_ID=<OAuth app client ID>
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=<OAuth app client secret>
# Optionally, configure a custom display name and icon:
CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar"
CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg"
The CODER_EXTERNAL_AUTH_0_ID environment variable is used as an identifier for the authentication provider.
This variable is used as part of the callback URL path that you must configure in your OAuth provider settings.
If the value in your callback URL doesn't match the CODER_EXTERNAL_AUTH_0_ID value, authentication will fail with redirect URI is not valid.
Set it with a value that helps you identify the provider.
For example, if you use CODER_EXTERNAL_AUTH_0_ID="primary-github" for your GitHub provider, configure your callback URL as https://example.com/external-auth/primary-github/callback.
By default, the redirect URL is built from the access URL Coder is configured with. You can override the base URL with:
CODER_EXTERNAL_AUTH_0_REDIRECT_URL=https://my.tld
This would change the callback in the above example to https://my.tld/external-auth/primary-github/callback (any path component on the redirect URL is ignored).
Using this setting can break OAuth, so use with caution. The override is intended to be used when the access URL is internal and either:
- Users access Coder via some other URL that proxies to the internal one.
- The redirect URL redirects to the internal access URL (this can be used to work around providers that require public domains for the callback).
Ultimately, the user must end up on the same domain they were on when the authentication flow was initiated.
Add an authentication button to the workspace template
Add the following code to any template to add a button to the workspace setup page which will allow you to authenticate with your provider:
data "coder_external_auth" "<github|gitlab|azure-devops|bitbucket-cloud|bitbucket-server|other>" {
id = "<USER_DEFINED_ID>"
}
# GitHub Example (CODER_EXTERNAL_AUTH_0_ID="primary-github")
# makes a GitHub authentication token available at data.coder_external_auth.github.access_token
data "coder_external_auth" "github" {
id = "primary-github"
}
Inside your Terraform code, you now have access to authentication variables. Reference the documentation for your chosen provider for more information on how to supply it with a token.
Workspace CLI
Use external-auth in the Coder CLI to access a token within the workspace:
coder external-auth access-token <USER_DEFINED_ID>
Git Authentication in Workspaces
Coder provides automatic Git authentication for workspaces through SSH authentication and Git-provider specific env variables.
When performing Git operations, Coder first attempts to use external auth provider tokens if available. If no tokens are available, it defaults to SSH authentication.
OAuth (external auth)
For Git providers configured with external authentication, Coder can use OAuth tokens for Git operations over HTTPS.
When using SSH URLs (like git@github.com:organization/repo.git), Coder uses SSH keys as described in the SSH Authentication section instead.
For Git operations over HTTPS, Coder automatically injects an external auth provider token.
This works through Git's GIT_ASKPASS mechanism, which Coder configures in each workspace.
GIT_ASKPASS tells Coder which Git host the operation is for, but never which provider to use.
Coder resolves the provider in two steps:
-
Coder considers only the providers the workspace's template declares with
data "coder_external_auth", and selects the one whoseCODER_EXTERNAL_AUTH_<N>_REGEXmatches the host. -
If every declared provider is configured and none match the host, Coder matches the host against all deployment providers.
This includes the case where the template declares no providers at all. This fallback keeps hosts that the template never declares, such as an unrelated Git server, reachable from the workspace.
Because the first step is scoped to the template, two workspaces built from different templates receive their own template's token for the same Git host, regardless of the order the providers appear in the deployment configuration.
To use OAuth tokens for Git authentication over HTTPS:
- Complete the OAuth authentication flow (Login with GitHub, Login with GitLab).
- Use HTTPS URLs when interacting with repositories (
https://github.com/organization/repo.git). - Coder automatically handles authentication. You can perform your Git operations as you normally would.
Behind the scenes, Coder:
- Stores your OAuth token securely in its database
- Sets up
GIT_ASKPASSat/tmp/coder.<random-string>/coderin your workspaces - Retrieves and injects the appropriate token when Git operations require authentication
To manually access these tokens within a workspace:
coder external-auth access-token <USER_DEFINED_ID>
SSH Authentication
Coder automatically generates an SSH key pair for each user that can be used for Git operations.
When you use SSH URLs for Git repositories, for example, git@github.com:organization/repo.git, Coder checks for and uses an existing SSH key.
If one is not available, it uses the Coder-generated one.
The coder gitssh command wraps the standard ssh command and injects the SSH key during Git operations.
This works automatically when you:
- Clone a repository using SSH URLs
- Pull/push changes to remote repositories
- Use any Git command that requires SSH authentication
You must add the SSH key to your Git provider.
Add your Coder SSH key to your Git provider
-
View your Coder Git SSH key:
coder publickey -
Add the key to your Git provider accounts:
PKCE Support
Proof Key for Code Exchange (PKCE) is an OAuth 2.0 security extension that prevents authorization code interception attacks. Coder supports PKCE when acting as an OAuth client to external identity providers.
Coder will usually assume PKCE support is available with "S256" as the code challenge method. Manual configuration is available to override any default behavior.
# Enable PKCE with S256 (recommended when supported)
CODER_EXTERNAL_AUTH_0_PKCE_METHODS="S256"
# Disable PKCE entirely
CODER_EXTERNAL_AUTH_0_PKCE_METHODS="none"
Git-provider specific env variables
Azure DevOps
Azure DevOps requires the following environment variables:
CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
CODER_EXTERNAL_AUTH_0_TYPE=azure-devops
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
# Ensure this value is your "Client Secret", not "App Secret"
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/authorize"
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
Azure DevOps (via Entra ID)
Azure DevOps (via Entra ID) requires the following environment variables:
CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
CODER_EXTERNAL_AUTH_0_TYPE=azure-devops-entra
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oauth2/authorize"
Note
Your app registration in Entra ID requires the
vso.code_writescope
Bitbucket Server
Bitbucket Server requires the following environment variables:
CODER_EXTERNAL_AUTH_0_ID="primary-bitbucket-server"
CODER_EXTERNAL_AUTH_0_TYPE=bitbucket-server
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.example.com/rest/oauth2/latest/authorize
When configuring your Bitbucket OAuth application, set the redirect Uniform Resource Identifier (URI) to https://example.com/external-auth/primary-bitbucket-server/callback.
This callback path includes the value of CODER_EXTERNAL_AUTH_0_ID.
Gitea
CODER_EXTERNAL_AUTH_0_ID="gitea"
CODER_EXTERNAL_AUTH_0_TYPE=gitea
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
# If self managed, set the Auth URL to your Gitea instance
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
The redirect URI for Gitea is https://coder.example.com/external-auth/gitea/callback.
GitHub
Use this section as a reference for environment variables to customize your setup or to integrate with an existing GitHub authentication.
For a more complete, step-by-step guide, follow the configure a GitHub OAuth app section instead.
CODER_EXTERNAL_AUTH_0_ID="primary-github"
CODER_EXTERNAL_AUTH_0_TYPE=github
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_REVOKE_URL=https://api.github.com/applications/<CLIENT ID>/grant
When configuring your GitHub OAuth application, set the authorization callback URL as https://example.com/external-auth/primary-github/callback, where primary-github matches your CODER_EXTERNAL_AUTH_0_ID value.
GitHub Enterprise
GitHub Enterprise requires the following environment variables:
CODER_EXTERNAL_AUTH_0_ID="primary-github"
CODER_EXTERNAL_AUTH_0_TYPE=github
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://github.example.com/api/v3/user"
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
CODER_EXTERNAL_AUTH_0_REGEX=^(https?://)?github\.example\.com(/.*)?$
The default regex matches only github.com, so set CODER_EXTERNAL_AUTH_0_REGEX to match your GitHub Enterprise host.
Anchor the expression with ^ and $ as in the example, so that it does not also match a look-alike host such as github.example.com.attacker.example.
When configuring your GitHub Enterprise OAuth application, set the authorization callback URL as https://example.com/external-auth/primary-github/callback, where primary-github matches your CODER_EXTERNAL_AUTH_0_ID value.
GitLab self-managed
GitLab self-managed requires the following environment variables:
CODER_EXTERNAL_AUTH_0_ID="primary-gitlab"
CODER_EXTERNAL_AUTH_0_TYPE=gitlab
# This value is the "Application ID"
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.example.com/oauth/token/info"
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.example.com/oauth/authorize"
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.example.com/oauth/token"
CODER_EXTERNAL_AUTH_0_REVOKE_URL="https://gitlab.example.com/oauth/revoke"
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.example\.com
When configuring your GitLab OAuth application, set the redirect URI to https://example.com/external-auth/primary-gitlab/callback.
Note that the redirect URI must include the value of CODER_EXTERNAL_AUTH_0_ID (in this example, primary-gitlab).
JFrog Artifactory
Visit the JFrog Artifactory guide for instructions on how to set up for JFrog Artifactory.
Self-managed Git providers
Use custom authentication and token URLs for self-managed Git provider deployments.
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
CODER_EXTERNAL_AUTH_0_REVOKE_URL="https://github.example.com/oauth/revoke"
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://example.com/oauth/token/info"
CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.com
Note
The
REGEXvariable must be set if using a custom Git domain.
Custom scopes
Optionally, you can request custom scopes:
CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
OAuth provider
Configure a GitHub OAuth app
-
- Set the authorization callback URL to
https://coder.example.com/external-auth/primary-github/callback, whereprimary-githubis the value you set forCODER_EXTERNAL_AUTH_0_ID. - Deactivate Webhooks.
- Enable fine-grained access to specific repositories or a subset of permissions for security.
- Set the authorization callback URL to
-
Adjust the GitHub app permissions.
You can use more or fewer permissions than are listed here, this example allows users to clone repositories:
Name Permission Description Contents Read & Write Grants access to code and commit statuses. Pull requests Read & Write Grants access to create and update pull requests. Workflows Read & Write Grants access to update files in .github/workflows/.Metadata Read-only Grants access to metadata written by GitHub Apps. Members Read-only Grants access to organization members and teams. -
Install the App for your organization. You can grant access to a subset of repositories.
-
Make the app installable by other users. In the app's Advanced tab, select Make this GitHub App public.
Without this, anyone outside the app's owning account or owning organization gets a GitHub 404 when they select Link GitHub in Coder. Each user must also install the app on their own account before linking. To surface an Install GitHub App link in the Coder UI, set the following environment variable:
CODER_EXTERNAL_AUTH_0_APP_INSTALL_URL=https://github.com/apps/<your-app-slug>/installations/new
Multiple External Providers (Premium)
Note
Configuring more than one external authentication provider requires a Premium license. For more details, contact your account team.
Below is an example configuration with multiple providers:
Important
To support regex matching for paths like
github\.com/org, add the followinggit configline to the Coder agent startup script:git config --global credential.useHttpPath true
# Provider 1) github.com
CODER_EXTERNAL_AUTH_0_ID=primary-github
CODER_EXTERNAL_AUTH_0_TYPE=github
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_0_REGEX=github\.com/org
# Provider 2) github.example.com
CODER_EXTERNAL_AUTH_1_ID=secondary-github
CODER_EXTERNAL_AUTH_1_TYPE=github
CODER_EXTERNAL_AUTH_1_CLIENT_ID=xxxxxx
CODER_EXTERNAL_AUTH_1_CLIENT_SECRET=xxxxxxx
CODER_EXTERNAL_AUTH_1_REGEX=github\.example\.com
CODER_EXTERNAL_AUTH_1_AUTH_URL="https://github.example.com/login/oauth/authorize"
CODER_EXTERNAL_AUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token"
CODER_EXTERNAL_AUTH_1_REVOKE_URL="https://github.example.com/login/oauth/revoke"
CODER_EXTERNAL_AUTH_1_VALIDATE_URL="https://github.example.com/api/v3/user"
When Coder can't resolve a single provider
When several providers serve the same Git host, HTTPS Git operations resolve the provider from the workspace template's declared providers, as described in OAuth (external auth).
Coder stops in two cases rather than pick a provider the template didn't ask for.
In both, the request fails and coder gitaskpass prints a warning and falls back to Git's own credential behavior, so the Git operation prompts for credentials or fails instead of using an unexpected token.
- Several of the template's declared providers match the host.
Coder can't tell which one the operation needs, so it returns an HTTP 404 naming each match.
Give the providers non-overlapping
CODER_EXTERNAL_AUTH_<N>_REGEXvalues so that only one matches the host, or fetch a token with an explicit provider ID usingcoder external-auth access-token <USER_DEFINED_ID>in your template's startup script. - The template declares a provider that the deployment no longer configures, and none of its other declared providers match the host. This happens when a provider is renamed or removed after a template started declaring it. Coder returns an HTTP 404 naming the missing provider instead of falling back to a provider the template never declared. A provider that the template declares and the deployment still configures keeps serving its own host, so only the hosts that relied on the missing provider are affected. Restore that provider's configuration, or update the template to declare a provider that the deployment configures.


