Repository navigation
Conversation
…3859) ## Why The catalog devcontainer snippets join `${localEnv:HOME}${localEnv:USERPROFILE}` for each bind-mount source. A Windows launch with both set produces an invalid path, and the container fails to start. #3852 asked for a fix. `devcontainer.json` cannot express one. Substitution is one non-greedy regex pass whose default is literal text, so `${localEnv:USERPROFILE:${localEnv:HOME}}` leaves a stray `}` or a literal `${localEnv}` in the path. Any form still naming `HOME` keeps the join on Windows. The maintainer chose to document the limit rather than move the snippets to Compose. That answer is recorded on #3852, and the issue closes at the promotion. The docs also disagreed with each other. `docs/host-setup.md` said the mounts only work from POSIX hosts, and `docs/ssh-signing.md` said the fallback handled Windows. ## What Changed - `docs/devcontainer.md` states that each host path must exist under the home directory the join finds, and what Docker does where one is absent. It gains a troubleshooting entry for this failure and for a native launch's conditions, including the `gh` config location and what is untested. - `docs/host-setup.md` and `docs/ssh-signing.md` define the supported route as opening the repo from inside a WSL2 distribution, and point at that entry. ## Evidence Measured on a Windows 11 host with Docker Desktop's WSL2 backend, using the Dev Containers extension's bundled CLI against a synthetic home holding every mount source. Each start used a scratch copy of the snippet with its image tag replaced, because the shipped tags do not start (#3858). Post-create was skipped. | Environment | Python snippet | .NET snippet | | --- | --- | --- | | Only `USERPROFILE` set | Started, mounted key readable in the container | Started, mounted key readable in the container | | Both set | Exit 1, `The filename, directory name, or volume label syntax is incorrect` | Exit 1, same error | - `gh help environment` documents `$AppData/GitHub CLI` ahead of `$HOME/.config/gh` on Windows. - Inside the default WSL2 distribution, `HOME` is set and `USERPROFILE` is unset. - Inside WSL2, `docker run --mount` refuses an absent bind source with `bind source path does not exist`. - From Windows, the same command exits 0. Docker Desktop creates the absent source on the host as an empty directory, and a write from the container reaches it. A source meant to be a file also becomes a directory. - A `devcontainer up` of the Python snippet against an empty home started, and left all three sources as directories on the host. A host-side append to `allowed_signers` then fails with `Is a directory`. - With those directories replaced by files and the old container only stopped, a second `up` fails at `docker start`. With the container removed first, then the directories replaced, a second `up` starts a new container, and the key is readable. - `Remove-Item Env:HOME` removes a session's `HOME` under PowerShell 7 and Windows PowerShell 5.1. **Not measured:** VS Code's own UI was not driven, so the Git Bash and Start menu sentences rest on process environment inheritance, and the docs list the VS Code launch as untested. Commit signing in such a container was not tested. Nothing ran on Linux or macOS, and no `devcontainer up` ran inside WSL2. #3852's Linux regression check does not apply, since no mount line changed. ## Local Pass Findings The findings this body listed as open at earlier pushes are fixed in this branch, and none stays open. The latest pass raised one more, declined: after the container is removed, an attached window does not offer **Dev Containers: Reopen in Container**. The extension's manifest enables that command in a local window, so the reader must return to one first. Under `GOVERNANCE.md` "Trust Boundaries and Hardening Effort" this earns no fix, since the failure is a visible missing palette entry, neither silent nor destructive, on a route the docs name as outside the supported one. One pass also asked about a user forwarding `USERPROFILE` into WSL2 through `WSLENV`. That is declined under `GOVERNANCE.md` "Trust Boundaries and Hardening Effort": no tooling here sets it, the default distribution measured above leaves it unset, and the failure is loud. ## Pre-existing findings, filed - #3860: `docs/devcontainer.md:32` and the snippets' mounts. `"readonly": true` is dropped by the CLI, so both read-only mounts are writable from the container. `pre-existing`, correctness. - #3858: both snippets' image tags stop a container before any mount. `pre-existing`, correctness. ## Pre-existing findings, not filed - `GOVERNANCE.md:347` lists "a devcontainer on Windows" beside "WSL2 on Windows" as separate routes, while these docs name WSL2 as the supported Windows devcontainer route. `pre-existing`, since the base docs differed from it the same way and this change does not touch that text. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
 |
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
The documentation includes Windows/WSL2 and Docker Desktop behavior that cannot be independently verified in this environment, so the cited native-Windows measurements require human confirmation.
No open issues 🎉
What changed in this PR
This documentation-only pull request promotes Windows devcontainer guidance from develop to main, documenting the supported WSL2 workflow and native Windows launch behavior when both HOME and USERPROFILE are set.
Changes:
- Documents Windows mount-path resolution and native launch requirements.
- Adds troubleshooting guidance for missing mount sources and GitHub CLI configuration.
- Aligns host setup and SSH-signing documentation with the supported WSL2 route.
| File | Summary | Review notes |
|---|---|---|
docs/devcontainer.md |
Adds Windows mount prerequisites, launch behavior, and troubleshooting guidance. | Two documentation nits: direct readers back to a local window before reopening the container, and limit required native sources to key files rather than every source. |
docs/host-setup.md |
Clarifies supported Windows devcontainer and native host-install routes. | No findings. |
docs/ssh-signing.md |
Updates Windows signing and bind-mount troubleshooting references. | No findings. |
Review effort: Lite
Owner
Author
|
Answering the review round on 60dd0682. It carries no thread, and its verdict headline and file table together hold these (3).
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3861 +/- ##
=======================================
Coverage 83.31% 83.31%
=======================================
Files 29 29
Lines 9956 9956
=======================================
Hits 8295 8295
Misses 1661 1661
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Promotes the change merged into
developsince promotion #3856 tomain.HOMEandUSERPROFILEboth set, whichdevcontainer.jsonsubstitution cannot fix. It defines the supported route as opening the repo from inside a WSL2 distribution, and states a native launch's conditions and what Docker does with an absent mount source. That pull request's body holds the measurements and what was not measured.Docs only. The defects those measurements found stay open: #3858 for image tags that stop a snippet starting, and #3860 for read-only mounts that are writable.
Closes #3852
🤖 Generated with Claude Code