opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-10-16 14:48:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: flatten lone index pages to single files (#30129)

Browse Source 
The beta docs engine turns a directory that holds only an `index.md`
into an empty collapsible section in the sidebar. Two pages on `main`
have that shape: `docs/admin/external-auth/index.md` and
`docs/ai-coder/agents/tools/index.md`. docs-engine is handling the shape
in its own code (the sidebar render fix in
https://github.com/coder/docs-engine/pull/196 and the sync-side handling
in https://github.com/coder/docs-engine/pull/195), and this change
removes it at the source by moving each page to a flat file:
`docs/admin/external-auth.md` and `docs/ai-coder/agents/tools.md`. Both
directories held only `index.md`, with no images or other files.

The change updates the two `docs/manifest.json` paths, 29 inbound
relative links across 17 pages, and the relative links inside the moved
pages (three images and two page links in `external-auth.md`, one page
link in `tools.md`), which now resolve one directory up. The ESR upgrade
table in `docs/install/operate/upgrade/esr-2.29-2.34-upgrade.md` is
re-padded because its link cells shrank, which is why that file shows 28
changed lines. No generator under `scripts/`, the docs-preview workflow,
or `docs/.style` references either path.

Published URLs stay the same, so no redirect is needed. coder.com's
`convertPathToRoute` strips the `index.md` or `.md` suffix, the
docs-preview workflow's `map_doc_path` maps `<dir>/index.md` and
`<dir>.md` to the same route, and docs-engine's `mapMdPath` returns
`admin/external-auth` and `ai-coder/agents/tools` for both the old and
new paths.

For verification, `docs/manifest.json` parses and all 471 of its paths
exist. `make pre-commit-light` passes, which covers markdownlint, the
table formatter, typos, emdash, and shellcheck, and `go run
./scripts/docshtmlcheck` passes. A local script resolved all 306
relative links in the changed files, and every one that the move touched
points at an existing file and heading. linkspector runs on this PR in
CI. A backport PR for `release/2.37` moves the same two pages plus
`admin/licensing` and `install/other`:
https://github.com/coder/coder/pull/30130.

This change was prepared with AI assistance. The AI agent that prepared
it ran the checks described above.

---

🤖 Built with AI assistance.
This commit is contained in:
Nick Vigilante
2026-09-30 14:34:33 -04:00
committed by GitHub
parent b6aab35a7b
commit 1fd383e4fd
20 changed files with 63 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/external-auth/index.md → docs/admin/external-auth.md
+5 -5
View File
@@ -88,7 +88,7 @@ Reference the documentation for your chosen provider for more information on how
### Workspace CLI
Use [`external-auth`](../../reference/cli/external-auth/index.md) in the Coder CLI to access a token within the workspace:
Use [`external-auth`](../reference/cli/external-auth/index.md) in the Coder CLI to access a token within the workspace:
```sh
coder external-auth access-token <USER_DEFINED_ID>
@@ -304,7 +304,7 @@ Note that the redirect URI must include the value of `CODER_EXTERNAL_AUTH_0_ID`
### JFrog Artifactory
Visit the [JFrog Artifactory](../../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
Visit the [JFrog Artifactory](./integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
## Self-managed Git providers
@@ -343,13 +343,13 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
- Enable fine-grained access to specific repositories or a subset of
permissions for security.
![Register GitHub App](../../images/admin/github-app-register.png)
![Register GitHub App](../images/admin/github-app-register.png)
1. Adjust the GitHub app permissions. You can use more or fewer permissions than
are listed here, this example allows users to clone
repositories:
![Adjust GitHub App Permissions](../../images/admin/github-app-permissions.png)
![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
| Name | Permission | Description |
|---------------|--------------|--------------------------------------------------------|
@@ -362,7 +362,7 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
1. Install the App for your organization. You may select a subset of
repositories to grant access to.
![Install GitHub App](../../images/admin/github-app-install.png)
![Install GitHub App](../images/admin/github-app-install.png)
1. Make the app installable by other users. In the app's **Advanced**
tab, select **Make this GitHub App public**.
docs/admin/integrations/jfrog-artifactory.md
+2 -2
View File
@@ -28,7 +28,7 @@ two type of modules that automate the JFrog Artifactory and Coder integration.
### JFrog-OAuth
This module works with both JFrog SaaS (for example, `example.jfrog.io`) and self-hosted (on-premises) Artifactory.
It uses Coder's [external-auth](../external-auth/index.md) feature, so each user authenticates with Artifactory through an OAuth flow, and Coder issues a user-scoped access token to each workspace.
It uses Coder's [external-auth](../external-auth.md) feature, so each user authenticates with Artifactory through an OAuth flow, and Coder issues a user-scoped access token to each workspace.
To set this up, follow these steps:
@@ -63,7 +63,7 @@ To set this up, follow these steps:
scope: "applied-permissions/user"
```
1. Add a new [external authentication](../external-auth/index.md) to Coder by setting these environment variables in a manner consistent with your Coder deployment.
1. Add a new [external authentication](../external-auth.md) to Coder by setting these environment variables in a manner consistent with your Coder deployment.
Replace `JFROG_URL` with your JFrog Artifactory base URL, and the client ID and secret with the values from step 1:
```dotenv
docs/admin/integrations/oauth2-provider/index.md
+1 -1
View File
@@ -214,7 +214,7 @@ The admin `PUT` also validates the stored name, so a self-registered client whos
- <a id="security-considerations"></a>[Security considerations](./security.md#security-considerations)
- <a id="limitations"></a>[Limitations](./security.md#limitations)
- Check [External Authentication](../../external-auth/index.md) for configuring Coder as an OAuth2 client
- Check [External Authentication](../../external-auth.md) for configuring Coder as an OAuth2 client
- Review the [API Reference](../../../reference/api/index.md) for complete endpoint documentation
## Feedback
docs/admin/integrations/vault.md
+1 -1
View File
@@ -21,7 +21,7 @@ will show you how to use these modules to integrate HashiCorp Vault with Coder.
The [`vault-github`](https://registry.coder.com/modules/vault-github) module is a Terraform module that allows you to
authenticate with Vault using a GitHub token. This module uses the existing
GitHub [external authentication](../external-auth/index.md) to get the token and authenticate with Vault.
GitHub [external authentication](../external-auth.md) to get the token and authenticate with Vault.
To use this module, add the following code to your Terraform configuration.
docs/admin/setup/index.md
+1 -1
View File
@@ -166,7 +166,7 @@ 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.
Please refer to the [external authentication](../external-auth/index.md) section for
Please refer to the [external authentication](../external-auth.md) section for
more information.
## Up Next
docs/admin/templates/extending-templates/external-auth.md
+2 -2
View File
@@ -9,7 +9,7 @@ service that requires authentication.
External auth providers are configured using environment variables in the Coder
Control Plane. See
[External Authentication](../../external-auth/index.md) for how to configure
[External Authentication](../../external-auth.md) for how to configure
them.
## Git Providers
@@ -45,7 +45,7 @@ For HTTPS Git operations, Coder selects from your template's declared providers
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)](../../external-auth/index.md#oauth-external-auth).
For the full rules, refer to [OAuth (external auth)](../../external-auth.md#oauth-external-auth).
To check the auth token being used **from inside a running workspace**, run:
docs/admin/templates/extending-templates/icons.md
+1 -1
View File
@@ -34,7 +34,7 @@ come bundled with your Coder deployment.
}
```
- [**Authentication Providers**](../../external-auth/index.md):
- [**Authentication Providers**](../../external-auth.md):
- Use icons for external authentication providers to make them recognizable.
You can set an icon for each provider by setting the
docs/admin/templates/open-in-coder.md
+1 -1
View File
@@ -17,7 +17,7 @@ approach for "Open in Coder" flows.
### 1. Set up git authentication
See [External Authentication](../external-auth/index.md) to set up Git authentication
See [External Authentication](../external-auth.md) to set up Git authentication
in your Coder deployment.
### 2. Modify your template to auto-clone repos
docs/ai-coder/agents/platform-controls/git-providers.md
+2 -2
View File
@@ -3,7 +3,7 @@ title: Git providers
---
Coder Agents leverages your existing
[external authentication](../../../admin/external-auth/index.md) configuration
[external authentication](../../../admin/external-auth.md) configuration
to power the in-chat diff viewer.
Self-hosted GitHub Enterprise deployments require one additional setting
(`API_BASE_URL`) for this feature to work.
@@ -13,7 +13,7 @@ Self-hosted GitHub Enterprise deployments require one additional setting
For public `github.com`, no additional configuration is needed.
For self-hosted GitHub Enterprise, add `API_BASE_URL` to your
[existing configuration](../../../admin/external-auth/index.md#github-enterprise):
[existing configuration](../../../admin/external-auth.md#github-enterprise):
```dotenv
CODER_EXTERNAL_AUTH_0_ID="primary-github"
docs/ai-coder/agents/platform-controls/index.md
+1 -1
View File
@@ -174,7 +174,7 @@ The concurrent agent pools described above are licensing limits, not deployment
### Git providers
Coder Agents leverages your existing
[external authentication](../../../admin/external-auth/index.md) configuration
[external authentication](../../../admin/external-auth.md) configuration
to power the in-chat diff viewer. Self-hosted GitHub Enterprise deployments
require additional configuration for this feature.
docs/ai-coder/agents/platform-controls/template-optimization.md
+2 -2
View File
@@ -35,7 +35,7 @@ With this setting, platform teams can apply stricter policies to agent workloads
The agent selects templates by reading their names and descriptions, the same metadata shown on the templates page in the Coder dashboard.
The agent's `list_templates` tool ranks matches by query relevance first, then by an affinity score that weights the developer's own recent template usage far more heavily than organization popularity.
It does not inspect the template's Terraform to understand what infrastructure is inside.
For the ranking details, refer to [list_templates](../tools/index.md#how-templates-are-ranked).
For the ranking details, refer to [list_templates](../tools.md#how-templates-are-ranked).
This means the template description is the single most important factor in
whether the agent picks the right template for a given task.
@@ -189,7 +189,7 @@ required:
only the permissions the agent needs (e.g., read/write access to specific
repositories, no admin access).
- **Configure external auth at the template level.** Use Coder's
[external authentication](../../../admin/external-auth/index.md) to provide scoped
[external authentication](../../../admin/external-auth.md) to provide scoped
git credentials. The agent uses the same external auth flow as any other
workspace, so credentials are managed centrally.
- **Avoid injecting long-lived secrets.** Prefer short-lived tokens or
docs/ai-coder/agents/tools/index.md → docs/ai-coder/agents/tools.md
+1 -1
View File
@@ -48,7 +48,7 @@ The agent uses three tools to provision a workspace:
| `read_template` | Read a template's parameters and presets |
| `create_workspace` | Create the workspace from a chosen template |
Administrators can restrict which templates these tools can use with the switches on the [Templates page](../platform-controls/template-optimization.md#restrict-available-templates).
Administrators can restrict which templates these tools can use with the switches on the [Templates page](./platform-controls/template-optimization.md#restrict-available-templates).
### list_templates
docs/ai-coder/ai-gateway/mcp.md
+2 -2
View File
@@ -23,7 +23,7 @@ AI Gateway can connect to MCP servers and inject tools automatically, enabling y
>
> [_Streamable HTTP_](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) is the only supported transport currently. In future releases we will support the (now deprecated) [_Server-Sent Events_](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#backwards-compatibility) transport.
AI Gateway makes use of [External Auth](../../admin/external-auth/index.md) applications, as they define OAuth2 connections to upstream services. If your External Auth application hosts a remote MCP server, you can configure AI Gateway to connect to it, retrieve its tools and inject them into requests automatically - all while using each individual user's access token.
AI Gateway makes use of [External Auth](../../admin/external-auth.md) applications, as they define OAuth2 connections to upstream services. If your External Auth application hosts a remote MCP server, you can configure AI Gateway to connect to it, retrieve its tools and inject them into requests automatically - all while using each individual user's access token.
For example, GitHub has a [remote MCP server](https://github.com/github/github-mcp-server?tab=readme-ov-file#remote-github-mcp-server) and we can use it as follows.
@@ -83,4 +83,4 @@ If you have [Coder MCP Server](../mcp-server.md) enabled, as well as have `CODER
- **Coder MCP tools not being injected**: in order for Coder MCP tools to be injected, the internal MCP server needs to be active. Follow the instructions in the [MCP Server](../mcp-server.md) page to enable it and ensure `CODER_AI_GATEWAY_INJECT_CODER_MCP_TOOLS` is set to `true`.
- **External Auth tools not being injected**: this is generally due to the requesting user not being authenticated against the [External Auth](../../admin/external-auth/index.md) app; when this is the case, no attempt is made to connect to the MCP server.
- **External Auth tools not being injected**: this is generally due to the requesting user not being authenticated against the [External Auth](../../admin/external-auth.md) app; when this is the case, no attempt is made to connect to the MCP server.
docs/get-started/customize-your-template/authenticate-to-github.md
+2 -2
View File
@@ -32,7 +32,7 @@ The `id` points at a provider configured on the Coder deployment, and the local
> External authentication lets a workspace sign in to an outside service, such as a Git provider, before it starts.
> A default Coder install includes a built-in GitHub app, so `id = "github"` works without extra setup.
> An admin can configure other providers (GitLab, Bitbucket, Azure DevOps, or generic OIDC) or replace the built-in GitHub app.
> To learn more, refer to [External authentication](../../admin/external-auth/index.md).
> To learn more, refer to [External authentication](../../admin/external-auth.md).
## Step 1: Require GitHub authentication
@@ -602,6 +602,6 @@ Or revisit the [Customize your template overview](./index.md) for the full list
## Learn more
- [External authentication](../../admin/external-auth/index.md) in the Coder documentation
- [External authentication](../../admin/external-auth.md) in the Coder documentation
- [coder_external_auth data source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/external_auth) in the Terraform Registry
- [Terraform data sources](https://developer.hashicorp.com/terraform/language/data-sources)
docs/install/operate/upgrade/esr-2.29-2.34-upgrade.md
+28 -28
View File
@@ -174,34 +174,34 @@ The CLI and dashboard gained smaller but meaningful workflow improvements:
The following changes introduced after 2.29 might break workflows, require manual
updates, or change administrator expectations:
| Initial State (2.29 and before) | New State (2.30-2.34) | Change Required |
|-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Terraform modules are downloaded during each workspace start. | Terraform modules are cached and pinned per template version. | Publish a new template version when upstream module changes should apply. Test templates that relied on fresh module downloads. See [speed up templates](../../../tutorials/best-practices/speed-up-templates.md). |
| Integrations may use experimental AI Bridge endpoints under `/api/experimental/aibridge/*`. | Experimental AI Bridge endpoints were removed after AI Gateway graduated to stable routes. | Update clients to use `/api/v2/aibridge/*` routes. Review API consumers again because `/api/v2/aibridge/interceptions` is now deprecated in favor of `/api/v2/aibridge/sessions`. See the [AI Gateway API reference](../../../reference/api/aigateway.md). |
| Unknown external OAuth providers did not default to PKCE. | Unknown external OAuth providers now default to PKCE. | If a provider does not support PKCE, set `CODER_EXTERNAL_AUTH_<N>_PKCE_METHODS=none`. See [external authentication](../../../admin/external-auth/index.md). |
| GitLab external auth required only the `write_repository` scope. | GitLab external auth now requires `write_repository` and `read_api` scopes by default. | Add the `read_api` scope to your GitLab OAuth application. Existing users must re-authenticate to obtain the new scope. If you set scopes explicitly via `CODER_EXTERNAL_AUTH_<N>_SCOPES`, add `read_api` there as well. See [external authentication](../../../admin/external-auth/index.md). |
| `--secure-auth-cookie` defaulted independently from the access URL. | Secure auth cookies are enabled automatically when `CODER_ACCESS_URL` uses HTTPS. | Confirm reverse proxies send the correct scheme headers. To preserve old behavior, explicitly set `CODER_SECURE_AUTH_COOKIE=false`. |
| SFTP and SCP connections always landed in `$HOME`. | SFTP and SCP now respect the workspace agent `dir` setting. | Update scripts that relied on implicit `$HOME` paths. Prefer explicit absolute paths for file transfers. |
| `coder_agent` `dir` attribute accepted any path without warning. | `dir` is deprecated and emits a warning. Non-`$HOME`/`~` values also break [Coder Desktop file sync](../../../user-guides/desktop/desktop-connect-sync.md). | Set `dir` to `$HOME` or omit it on `coder_agent` resources. The attribute still works in 2.34 but will be removed in a future release. |
| Pre-2.28 Tasks templates might still exist in older deployments. | The pre-2.28 Tasks template format is no longer supported as of 2.30. | Update Tasks templates to use `app_id` instead of the deprecated `sidebar_app` flow. |
| Tasks is the primary AI coding workflow. | Coder Agents is the long-term replacement, and Tasks is supported through the 2.34 ESR window (into 2026). | Plan migration from the Tasks API to the Chats API and [Coder Agents](../../../ai-coder/agents/index.md). See [Migrating from the Tasks API to the Chats API](../../../ai-coder/agents/tasks-to-chats-migration.md). |
| AI Gateway injected MCP tools can be used for tool exposure. | Injected MCP tools are deprecated. | Move new integrations toward Coder Agents MCP server configuration or the MCP server flow. See [AI Gateway MCP](../../../ai-coder/ai-gateway/mcp.md) and [MCP servers](../../../ai-coder/agents/platform-controls/mcp-servers.md). |
| AI Bridge is opt-in via `CODER_AIBRIDGE_ENABLED` (default `false`). | The toggle is renamed to `CODER_AI_GATEWAY_ENABLED` and now defaults to `true`. | The in-memory AI Gateway now starts on every deployment. Set `CODER_AI_GATEWAY_ENABLED=false`, or the deprecated `CODER_AIBRIDGE_ENABLED` alias which still works, to keep the old behavior. |
| AI Gateway providers are configured with `CODER_AIBRIDGE_PROVIDER_*` or `CODER_AI_GATEWAY_PROVIDER_*` env vars. | Provider configuration is stored in the database. Env vars seed the database once on first startup, then are deprecated. | After upgrade, visit `/ai/settings/providers` to verify seeded providers, then remove the env vars. Coderd fails to start if env vars drift from the seeded database row. See [AI Gateway providers](../../../ai-coder/ai-gateway/providers.md). |
| Regular users can read their own AI Gateway interceptions. | Only owners and auditors can read AI Gateway interception data. | Update dashboards, scripts, or user workflows that expected self-service interception reads. This intentionally narrows the RBAC surface. |
| `coder groups list -o json` returns the old command output shape. | `coder groups list -o json` returns a flat structure matching other list commands. | Update scripts that parse this command output. |
| `coder tokens rm` deletes token records by default. | `coder tokens rm` expires tokens by default and keeps records for auditability. | Use `coder tokens rm --delete` only when the token record must be deleted. Update scripts that expect removed tokens to disappear from token history. |
| Deprecated Prometheus metrics are still emitted. | Deprecated Prometheus metrics were removed. | Update dashboards and alerts that use `coderd_api_workspace_latest_build_total` or `coderd_oauth2_external_requests_rate_limit_total`. Use the replacement metrics without the `_total` suffix. |
| Authenticated rate limits are effectively shared by client IP in some deployments. | Authenticated request rate limits are keyed by user. | Review monitoring and expectations for NATed users or shared proxies. Per-user limits now apply more consistently after API key precheck. |
| `coder login` can run while `CODER_SESSION_TOKEN` is set. | `coder login` errors when `CODER_SESSION_TOKEN` is set. | Unset `CODER_SESSION_TOKEN` in interactive login flows. Keep using the environment variable for non-interactive automation. |
| Workspace starts with new parameters can proceed without an explicit stop in some flows. | Workspace starts with new parameters stop the workspace before starting. | Expect downtime when applying new parameters. Update automation that assumes the workspace remains running. |
| `mode=auto` workspace links can silently create workspaces with prefilled parameters. | Users must confirm workspace auto-creation before provisioning starts. | Update Open in Coder buttons, runbooks, or internal flows that expect one-click workspace creation without a consent dialog. |
| Users with `--login-type none` are common for automation. | `--login-type none` is deprecated. | For Premium deployments, migrate automation to service accounts. For OSS deployments, use regular users with password, GitHub, or OIDC authentication. See [headless auth](../../../admin/users/headless-auth.md). |
| Terminal commands can be executed from URL parameters without extra confirmation. | The dashboard requires confirmation before executing terminal commands from URLs. | Update runbooks or deep links that expected immediate terminal execution. This protects users from accidental command execution. |
| Agent SSH port forwarding is always available when the agent allows SSH. | Reverse and local port forwarding can be disabled per agent. | Review templates and IDE workflows before enabling `--block-reverse-port-forwarding` or `--block-local-port-forwarding`. See [port forwarding](../../../admin/networking/port-forwarding.md). |
| `PATCH /api/v2/templates/{template}` accepts value fields for metadata updates. | Template metadata update fields are optional pointer fields in the SDK, and 304 responses were removed. | Update SDK consumers and direct API clients that patch template metadata. Send only fields that should change, including false or zero values explicitly. |
| External provisioner daemons use the 2.29 provisionerd protocol. | The provisionerd protocol changed for provisioner operations and file upload/download. | Update external provisioner daemons to the matching 2.34 protocol. The protocol reserves removed fields such as `stop_modules`, `exp_reuse_terraform_workspace`, and `user_secrets`, and adds `DownloadFile`. |
| Helm chart health probes and observability bind addresses use older chart defaults. | Readiness and liveness probes have `enabled` toggles and more fields, and Prometheus/pprof addresses are overridable. | Review custom Helm values for probe behavior and observability bindings. Prefer restricting pprof to a local address when exposing diagnostics. |
| Initial State (2.29 and before) | New State (2.30-2.34) | Change Required |
|-----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Terraform modules are downloaded during each workspace start. | Terraform modules are cached and pinned per template version. | Publish a new template version when upstream module changes should apply. Test templates that relied on fresh module downloads. See [speed up templates](../../../tutorials/best-practices/speed-up-templates.md). |
| Integrations may use experimental AI Bridge endpoints under `/api/experimental/aibridge/*`. | Experimental AI Bridge endpoints were removed after AI Gateway graduated to stable routes. | Update clients to use `/api/v2/aibridge/*` routes. Review API consumers again because `/api/v2/aibridge/interceptions` is now deprecated in favor of `/api/v2/aibridge/sessions`. See the [AI Gateway API reference](../../../reference/api/aigateway.md). |
| Unknown external OAuth providers did not default to PKCE. | Unknown external OAuth providers now default to PKCE. | If a provider does not support PKCE, set `CODER_EXTERNAL_AUTH_<N>_PKCE_METHODS=none`. See [external authentication](../../../admin/external-auth.md). |
| GitLab external auth required only the `write_repository` scope. | GitLab external auth now requires `write_repository` and `read_api` scopes by default. | Add the `read_api` scope to your GitLab OAuth application. Existing users must re-authenticate to obtain the new scope. If you set scopes explicitly via `CODER_EXTERNAL_AUTH_<N>_SCOPES`, add `read_api` there as well. See [external authentication](../../../admin/external-auth.md). |
| `--secure-auth-cookie` defaulted independently from the access URL. | Secure auth cookies are enabled automatically when `CODER_ACCESS_URL` uses HTTPS. | Confirm reverse proxies send the correct scheme headers. To preserve old behavior, explicitly set `CODER_SECURE_AUTH_COOKIE=false`. |
| SFTP and SCP connections always landed in `$HOME`. | SFTP and SCP now respect the workspace agent `dir` setting. | Update scripts that relied on implicit `$HOME` paths. Prefer explicit absolute paths for file transfers. |
| `coder_agent` `dir` attribute accepted any path without warning. | `dir` is deprecated and emits a warning. Non-`$HOME`/`~` values also break [Coder Desktop file sync](../../../user-guides/desktop/desktop-connect-sync.md). | Set `dir` to `$HOME` or omit it on `coder_agent` resources. The attribute still works in 2.34 but will be removed in a future release. |
| Pre-2.28 Tasks templates might still exist in older deployments. | The pre-2.28 Tasks template format is no longer supported as of 2.30. | Update Tasks templates to use `app_id` instead of the deprecated `sidebar_app` flow. |
| Tasks is the primary AI coding workflow. | Coder Agents is the long-term replacement, and Tasks is supported through the 2.34 ESR window (into 2026). | Plan migration from the Tasks API to the Chats API and [Coder Agents](../../../ai-coder/agents/index.md). See [Migrating from the Tasks API to the Chats API](../../../ai-coder/agents/tasks-to-chats-migration.md). |
| AI Gateway injected MCP tools can be used for tool exposure. | Injected MCP tools are deprecated. | Move new integrations toward Coder Agents MCP server configuration or the MCP server flow. See [AI Gateway MCP](../../../ai-coder/ai-gateway/mcp.md) and [MCP servers](../../../ai-coder/agents/platform-controls/mcp-servers.md). |
| AI Bridge is opt-in via `CODER_AIBRIDGE_ENABLED` (default `false`). | The toggle is renamed to `CODER_AI_GATEWAY_ENABLED` and now defaults to `true`. | The in-memory AI Gateway now starts on every deployment. Set `CODER_AI_GATEWAY_ENABLED=false`, or the deprecated `CODER_AIBRIDGE_ENABLED` alias which still works, to keep the old behavior. |
| AI Gateway providers are configured with `CODER_AIBRIDGE_PROVIDER_*` or `CODER_AI_GATEWAY_PROVIDER_*` env vars. | Provider configuration is stored in the database. Env vars seed the database once on first startup, then are deprecated. | After upgrade, visit `/ai/settings/providers` to verify seeded providers, then remove the env vars. Coderd fails to start if env vars drift from the seeded database row. See [AI Gateway providers](../../../ai-coder/ai-gateway/providers.md). |
| Regular users can read their own AI Gateway interceptions. | Only owners and auditors can read AI Gateway interception data. | Update dashboards, scripts, or user workflows that expected self-service interception reads. This intentionally narrows the RBAC surface. |
| `coder groups list -o json` returns the old command output shape. | `coder groups list -o json` returns a flat structure matching other list commands. | Update scripts that parse this command output. |
| `coder tokens rm` deletes token records by default. | `coder tokens rm` expires tokens by default and keeps records for auditability. | Use `coder tokens rm --delete` only when the token record must be deleted. Update scripts that expect removed tokens to disappear from token history. |
| Deprecated Prometheus metrics are still emitted. | Deprecated Prometheus metrics were removed. | Update dashboards and alerts that use `coderd_api_workspace_latest_build_total` or `coderd_oauth2_external_requests_rate_limit_total`. Use the replacement metrics without the `_total` suffix. |
| Authenticated rate limits are effectively shared by client IP in some deployments. | Authenticated request rate limits are keyed by user. | Review monitoring and expectations for NATed users or shared proxies. Per-user limits now apply more consistently after API key precheck. |
| `coder login` can run while `CODER_SESSION_TOKEN` is set. | `coder login` errors when `CODER_SESSION_TOKEN` is set. | Unset `CODER_SESSION_TOKEN` in interactive login flows. Keep using the environment variable for non-interactive automation. |
| Workspace starts with new parameters can proceed without an explicit stop in some flows. | Workspace starts with new parameters stop the workspace before starting. | Expect downtime when applying new parameters. Update automation that assumes the workspace remains running. |
| `mode=auto` workspace links can silently create workspaces with prefilled parameters. | Users must confirm workspace auto-creation before provisioning starts. | Update Open in Coder buttons, runbooks, or internal flows that expect one-click workspace creation without a consent dialog. |
| Users with `--login-type none` are common for automation. | `--login-type none` is deprecated. | For Premium deployments, migrate automation to service accounts. For OSS deployments, use regular users with password, GitHub, or OIDC authentication. See [headless auth](../../../admin/users/headless-auth.md). |
| Terminal commands can be executed from URL parameters without extra confirmation. | The dashboard requires confirmation before executing terminal commands from URLs. | Update runbooks or deep links that expected immediate terminal execution. This protects users from accidental command execution. |
| Agent SSH port forwarding is always available when the agent allows SSH. | Reverse and local port forwarding can be disabled per agent. | Review templates and IDE workflows before enabling `--block-reverse-port-forwarding` or `--block-local-port-forwarding`. See [port forwarding](../../../admin/networking/port-forwarding.md). |
| `PATCH /api/v2/templates/{template}` accepts value fields for metadata updates. | Template metadata update fields are optional pointer fields in the SDK, and 304 responses were removed. | Update SDK consumers and direct API clients that patch template metadata. Send only fields that should change, including false or zero values explicitly. |
| External provisioner daemons use the 2.29 provisionerd protocol. | The provisionerd protocol changed for provisioner operations and file upload/download. | Update external provisioner daemons to the matching 2.34 protocol. The protocol reserves removed fields such as `stop_modules`, `exp_reuse_terraform_workspace`, and `user_secrets`, and adds `DownloadFile`. |
| Helm chart health probes and observability bind addresses use older chart defaults. | Readiness and liveness probes have `enabled` toggles and more fields, and Prometheus/pprof addresses are overridable. | Review custom Helm values for probe behavior and observability bindings. Prefer restricting pprof to a local address when exposing diagnostics. |
<a id="upgrading"></a>
docs/install/plan/architecture.md
+4 -4
View File
@@ -108,10 +108,10 @@ Users will likely need to pull source code and other artifacts from a git
provider. The Coder control plane and workspaces will need network connectivity
to the git provider.
- [GitHub Enterprise](../../admin/external-auth/index.md#github-enterprise)
- [GitLab](../../admin/external-auth/index.md#gitlab-self-managed)
- [BitBucket](../../admin/external-auth/index.md#bitbucket-server)
- [Other Providers](../../admin/external-auth/index.md#self-managed-git-providers)
- [GitHub Enterprise](../../admin/external-auth.md#github-enterprise)
- [GitLab](../../admin/external-auth.md#gitlab-self-managed)
- [BitBucket](../../admin/external-auth.md#bitbucket-server)
- [Other Providers](../../admin/external-auth.md#self-managed-git-providers)
### Artifact Manager (Optional)
docs/manifest.json
+2 -2
View File
@@ -775,7 +775,7 @@
{
"title": "External authentication",
"description": "Configure external authentication so workspaces can access Git providers and other OAuth services.",
"path": "./admin/external-auth/index.md",
"path": "./admin/external-auth.md",
"icon_path": "./images/icons/plug.svg"
},
{
@@ -1125,7 +1125,7 @@
{
"title": "Tools",
"description": "How Coder Agents uses tool calls to select templates and create workspaces",
"path": "./ai-coder/agents/tools/index.md"
"path": "./ai-coder/agents/tools.md"
},
{
"title": "Chat sharing",
docs/reference/glossary.md
+1 -1
View File
@@ -278,7 +278,7 @@ Refer to [Resource persistence](../admin/templates/extending-templates/resource-
### External authentication
In-workspace OAuth to Git providers, artifact registries, and similar services, configured with `CODER_EXTERNAL_AUTH_*` variables.
Refer to [External authentication](../admin/external-auth/index.md).
Refer to [External authentication](../admin/external-auth.md).
### External provisioner
docs/tutorials/cloning-git-repositories.md
+3 -3
View File
@@ -22,9 +22,9 @@ authorization. This can be achieved by using the Git provider, such as GitHub,
as an authentication method. If you don't know how to do that, we have written
documentation to help you:
- [GitHub](../admin/external-auth/index.md#github)
- [GitLab self-managed](../admin/external-auth/index.md#gitlab-self-managed)
- [Self-managed git providers](../admin/external-auth/index.md#self-managed-git-providers)
- [GitHub](../admin/external-auth.md#github)
- [GitLab self-managed](../admin/external-auth.md#gitlab-self-managed)
- [Self-managed git providers](../admin/external-auth.md#self-managed-git-providers)
With the authentication in place, it is time to set up the template to use the
[Git Clone module](https://registry.coder.com/modules/git-clone) from the
docs/tutorials/template-from-scratch.md
+1 -1
View File
@@ -179,7 +179,7 @@ resource "coder_agent" "main" {
Because Docker is running on the same machine as the control plane, there is no need to
authenticate `coder_agent`. But if your `coder_agent` is running on a remote
host, your template will need
[authentication credentials](../admin/external-auth/index.md).
[authentication credentials](../admin/external-auth.md).
This template's agent also runs a startup script, sets environment variables,
and provides metadata.