mirror of https://github.com/coder/coder.git synced 2026-11-02 21:50:08 +08:00

Files

T

df6a33ad37 docs: fix broken extending-templates examples (dynamic-parameters, docker-in-workspaces) (#28100 )

## Summary

Fixes broken examples on the `extending-templates` pages surfaced by the
DOCS-637 runtime drift sweep, and completes the dangling `external-auth`
reference. Verified against `main` and the CLI source (`coder templates
init --id`, `coder templates push`).

## Changes

| Page | Fix |
|------|-----|
| `dynamic-parameters.md` | The **Dynamic Validation** snippet
referenced an undefined `show_cpu_cores` through a stray `count =
data.coder_parameter.show_cpu_cores.value ? 1 : 0` line copied from the
earlier Hide/Show Options example. Standalone copy failed `terraform
validate`. Removed the `count` line (and its misleading "Only show this
parameter" comment) so the snippet is self-contained. The valid
occurrence in the Hide/Show example (where `show_cpu_cores` is defined)
is untouched. |
| `docker-in-workspaces.md` | The rootless Podman step used `echo
"kubernetes-with-podman" \| coder templates init`, but
`kubernetes-with-podman` isn't a built-in starter id, so the command
scaffolds nothing. Step 4 now starts from the built-in `kubernetes`
starter (`coder templates init --id kubernetes`) and shows the minimal
Podman delta inline: the maintained `codercom/example-podman:ubuntu`
base image, the `container.apparmor.security.beta.kubernetes.io/dev =
unconfined` pod annotation, and a `github.com/fuse` device limit. The
starter already runs as UID/GID 1000 with `run_as_non_root`, which
rootless Podman needs. Also switches the deprecated `coder templates
create` to `coder templates push`. Follow-up from review: swapped
`ghcr.io/coder/podman` for the maintained
`codercom/example-podman:ubuntu` image and linked its source, added a
note that the AppArmor annotation is deprecated on Kubernetes 1.30+
(`securityContext.appArmorProfile`), and added an EKS Auto Mode caveat
to the Bottlerocket section. |
| `external-auth.md` | The **External Auth Providers** sentence
dead-ended at "...in the Coder Control Plane. See" with no link.
Completed it with a link to the admin External Authentication page
(`../../external-auth/index.md`), the target chosen in review. |

## Dependency

The `docker-in-workspaces.md` example now references
`codercom/example-podman:ubuntu`, published by coder/images#339. That PR
is approved but should merge (and publish the image to Docker Hub)
before this PR merges, so the docs don't point at an image that doesn't
exist yet.

Linear: https://linear.app/codercom/issue/DOCS-645

> This PR was created with AI assistance (Coder Agents).

---------

Co-authored-by: Ben Potter <me@bpmct.net>
Co-authored-by: Ben Potter <ben@coder.com>

2026-08-24 08:24:26 -04:00

3.9 KiB

Raw Blame History

External Authentication

Coder integrates with any OpenID Connect provider to automate away the need for developers to authenticate with external services within their workspace. This can be used to authenticate with git providers, private registries, or any other service that requires authentication.

External Auth Providers

External auth providers are configured using environment variables in the Coder Control Plane. See External Authentication for how to configure them.

Git Providers

When developers use git inside their workspace, they are prompted to authenticate. After that, Coder will store and refresh tokens for future operations.

Require git authentication in templates

If your template requires git authentication (e.g. running git clone in the startup_script), you can require users authenticate via git prior to creating a workspace:

Native git authentication will auto-refresh tokens

Tip

This is the preferred authentication method.

By default, the coder agent will configure native git authentication via the GIT_ASKPASS environment variable. Meaning, with no additional configuration, external authentication will work with native git commands.

The providers your template declares also determine which token native git commands receive. For HTTPS Git operations, Coder selects from your template's declared providers first, and only matches against every provider configured on the deployment when none of the declared providers serve that host. If two of your template's declared providers match the same host, Coder refuses the request instead of guessing between them. Coder also refuses when none of your declared providers match the host and one of them is missing from the deployment's configuration, rather than fall back to a provider your template never declared. A missing declaration doesn't affect hosts that your other declared providers still serve. For the full rules, refer to OAuth (external auth).

To check the auth token being used from inside a running workspace, run:

# If the exit code is non-zero, then the user is not authenticated with the
# external provider.
coder external-auth access-token <external-auth-id>

Note: Some IDE's override the GIT_ASKPASS environment variable and need to be configured.

VSCode

Use the Coder extension to automatically configure these settings for you!

Otherwise, you can manually configure the following settings:

Set git.terminalAuthentication to false
Set git.useIntegratedAskPass to false

Hard coded tokens do not auto-refresh

If the token is required to be inserted into the workspace, for example GitHub cli, the auth token can be inserted from the template. This token will not auto-refresh. The following example will authenticate via GitHub and auto-clone a repo into the ~/coder directory.

data "coder_external_auth" "github" {
  # Matches the ID of the external auth provider in Coder.
  id = "github"
}

resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
  dir  = "~/coder"
  env = {
    GITHUB_TOKEN : data.coder_external_auth.github.access_token
  }
  startup_script = <<EOF
if [ ! -d ~/coder ]; then
    git clone https://github.com/coder/coder
fi
EOF
}

See the Terraform provider documentation for all available options.

3.9 KiB Raw Blame History