Repository navigation
docs: update dev containers documentation to reflect GA status - #20847
Conversation
- Remove 'early access' language (feature is GA) - Update minimum version to 2.24.0 (agent injection requirement) - Add environment variables section with correct defaults: - CODER_AGENT_DEVCONTAINERS_ENABLE (default: true, v2.24.0+) - CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE (default: true, v2.25.0+) - CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE (default: false, v2.26.0+) - Add Configuration Modes section (Manual vs Project Discovery) - Remove SSH limitation (no --container flag needed) - Simplify template examples (env vars not needed by default) - Add Windows not supported notices - Update features section to reflect current capabilities Closes #XXXXX
CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE was introduced in v2.25.0 via cherry-pick commit e6ec957, not v2.26.0.
The docker_container resource was shown twice in the same section. The second example (in Project Discovery Mode) is more useful since it shows the actual configuration change needed.
mafredri
left a comment
mafredri
left a comment
There was a problem hiding this comment.
I think this is mostly good 👍🏻. Some suggestions and nits inline.
|
|
||
| ### Manual Configuration | ||
|
|
||
| Use the `coder_devcontainer` Terraform resource to explicitly define which dev |
| Enable automatic discovery of dev containers in git repositories using | ||
| environment variables. This approach: | ||
|
|
||
| - Automatically scans for `.devcontainer/devcontainer.json` files |
There was a problem hiding this comment.
Only this specific path? IIRC [root]/devcontainer.json and some other permutations are also valid.
| Enables the dev containers integration in the Coder agent. | ||
|
|
||
| ```terraform | ||
| env = [ |
There was a problem hiding this comment.
I suggest removing these code samples. It' unclear where this env field should be applied. The user might mistake it for coder_agent resource which won't work.
The earlier code sample is better since it includes the entire docker resource, making it explicit that we're defining it above the agent. But in the name of DRY, let's avoid too many repeats of the whole tf.
| - Automatically scans for `.devcontainer/devcontainer.json` files | ||
| - Can auto-start discovered containers | ||
| - Useful for dynamic development environments | ||
| - Respects `.gitignore` patterns |
There was a problem hiding this comment.
I'm worried about duplication and inconsistency here. The documentation for the ENV is not the same as here. If you want to keep something here, give a short intro (essentialls/most wow factor), and link to the env docs.
|
|
||
| - Scan the agent directory for git repositories | ||
| - Look for `.devcontainer/devcontainer.json` or `.devcontainer.json` files | ||
| - Register discovered dev containers automatically |
There was a problem hiding this comment.
| - Register discovered dev containers automatically | |
| - Discovered dev containers are automatically surfaced in the Coder UI |
Perhaps, "register" is a broad term here that doesn't mean much to the user IMO.
| ] | ||
| ``` | ||
|
|
||
| When enabled (the default), the agent will: |
There was a problem hiding this comment.
This is kind of the third repeat of default (default: true, #enabled by default, the default). I think we only need to mention it once.
| When enabled, discovered dev containers will be automatically built and started | ||
| during workspace initialization. This only applies to dev containers found via | ||
| project discovery. Dev containers defined with the `coder_devcontainer` resource | ||
| always auto-start regardless of this setting. |
There was a problem hiding this comment.
Should we mention the devcontainer.json level control here? Was it called ignore? Or do we have autostart too?
| - Coder CLI version 2.22.0 or later | ||
| - Coder version 2.24.0 or later | ||
| - Coder CLI version 2.24.0 or later | ||
| - **Linux or macOS workspace** - Dev containers are not supported on Windows |
There was a problem hiding this comment.
| - **Linux or macOS workspace** - Dev containers are not supported on Windows | |
| - **Linux or macOS workspace**, dev containers are not supported on Windows |
I do not like AI dashes 😂
| limitations: | ||
| The dev containers integration has the following limitations: | ||
|
|
||
| - **Not supported on Windows** - Dev containers require a Linux or macOS workspace |
There was a problem hiding this comment.
| - **Not supported on Windows** - Dev containers require a Linux or macOS workspace | |
| - Not supported on Windows |
Mainly, I want the AI dash gone, but IMO we don't need to many repeats of the same information.
The agent scans for both .devcontainer/devcontainer.json and .devcontainer.json as verified in agent/agentcontainers/api.go
These examples were confusing as the env vars should be set on the compute resource, not the Coder agent. The section heading and main example already show where to set them.
Replaced bullet list with concise description and linked to Environment Variables section for details, avoiding duplication between the intro and the ENV docs.
- Removed '(the default)' to avoid redundancy with the Default line above - Changed 'Register' to 'Surface...in the Coder UI' for clearer user-facing language
- Replace em dash with comma in Prerequisites - Remove redundant text from Windows limitation
Standardize terminology by capitalizing 'Dev Containers' as a proper noun throughout all devcontainer documentation, matching industry convention and official Dev Containers specification branding.
Document the customizations.coder block in devcontainer.json: - ignore: hide containers from Coder UI - autoStart: control per-container auto-start behavior Also fix incomplete sentence in DISCOVERY_AUTOSTART_ENABLE section.
mafredri
left a comment
mafredri
left a comment
There was a problem hiding this comment.
I didn't do a thorough re-review, more like a quick scan, but LGTM! 
Updates the dev containers documentation to accurately reflect that the feature is generally available and document all configuration options.
Closes coder/internal#1138
🤖 PR was written by Claude Sonnet 4.5 Thinking using Coder Mux and reviewed by a human 👩