Repository navigation
Document a Windows Devcontainer Launch With HOME and USERPROFILE Set - #3859
Conversation
…PROFILE
The snippets' bind mounts join ${localEnv:HOME}${localEnv:USERPROFILE}.
A Windows launch with both set gives an invalid path, and the container fails to start.
The substitution has no fallback syntax, so devcontainer.json cannot choose one of them.
The maintainer chose to document the limit rather than move the snippets to Compose.
The docs also disagreed: one said the mounts only work from POSIX hosts, and another said the fallback handled Windows.
Each now states what a real start measured on a Windows host.
A local review found the first wording overclaimed. The measured start used a synthetic home holding every mount source, and a scratch image tag. On a real Windows host the gh mount source can be missing, since gh defaults to AppData there. The removal advice for a persistent HOME could also break a host's git and SSH configuration.
A second local review found the route undefined, since a Docker Desktop WSL2 backend reads as already being on it. The steps also left a persistent HOME and an empty gh mount unanswered. And they named signing as the only untested part of a route only a CLI start has exercised.
|
A recorded local strict-review pass covers head |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
The local pass found a persistent HOME told it had no native launch, which removing the variable from one session disproves. It also found "this route" ambiguous, and the evidence sentence silent on what the start depended on.
There was a problem hiding this comment.
🟡 Changes recommended
The documentation still contains two active issues: it misstates the required HOME condition and does not precisely describe the validation scope and test setup.
2 open issues
What changed in this PR
This documentation-only PR clarifies Windows devcontainer launch behavior when HOME and USERPROFILE are both set, and aligns host setup and SSH-signing guidance around WSL2 as the supported route.
Changes:
- Documents mount-source requirements and native Windows troubleshooting.
- Identifies WSL2 as the supported Windows devcontainer route.
- Updates host setup and SSH-signing references.
- Records two wording nits in the validation and process-environment guidance.
| File | Summary |
|---|---|
docs/ssh-signing.md |
Aligns Windows signing and bind-mount guidance with the supported WSL2 route. |
docs/host-setup.md |
Clarifies supported Windows host and devcontainer routes. |
docs/devcontainer.md |
Adds mount prerequisites and Windows troubleshooting guidance; contains two wording nits regarding the HOME process condition and validation scope. |
Review effort: Lite
A local pass found the evidence sentence read as one start, and the conditions omitted the gitconfig the container copies.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #3859 +/- ##
========================================
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:
|
|
A recorded local strict-review pass covers head |
A local pass found ".gitconfig must exist" unsupported, since it is copied rather than mounted and its absence does not stop a start.
A local pass found the sentence stated an extension step no measurement drove.
The docs said Docker refuses an absent source, which measures true inside WSL2 and false from Windows. A native launch creates the absent path on the host as an empty directory, and the container starts.
A local pass found the created directory blocks the host setup steps with no documented remedy. A real start against an empty home measures that, and the evidence sentence now names the backend.
|
A recorded local strict-review pass covers head |
A local pass, then a measurement, found the old container cannot restart once its mount source changes from a directory to a file.
A local pass found the rebuild command is hidden in a local window, and the delete ran against a live mount. Removing the container first measures clean, and a plain reopen then creates a new one.
|
A recorded local strict-review pass covers head |
…e Variables (#3861) Promotes the change merged into `develop` since promotion #3856 to `main`. - [#3859](#3859) documents a Windows devcontainer launch with `HOME` and `USERPROFILE` both set, which `devcontainer.json` substitution 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](https://claude.com/claude-code)

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.jsoncannot 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 namingHOMEkeeps 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.mdsaid the mounts only work from POSIX hosts, anddocs/ssh-signing.mdsaid the fallback handled Windows.What Changed
docs/devcontainer.mdstates 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 theghconfig location and what is untested.docs/host-setup.mdanddocs/ssh-signing.mddefine 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.
USERPROFILEsetThe filename, directory name, or volume label syntax is incorrectgh help environmentdocuments$AppData/GitHub CLIahead of$HOME/.config/ghon Windows.HOMEis set andUSERPROFILEis unset.docker run --mountrefuses an absent bind source withbind source path does not exist.devcontainer upof the Python snippet against an empty home started, and left all three sources as directories on the host. A host-side append toallowed_signersthen fails withIs a directory.upfails atdocker start. With the container removed first, then the directories replaced, a secondupstarts a new container, and the key is readable.Remove-Item Env:HOMEremoves a session'sHOMEunder 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 upran 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
USERPROFILEinto WSL2 throughWSLENV. That is declined underGOVERNANCE.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
docs/devcontainer.md:32and the snippets' mounts."readonly": trueis dropped by the CLI, so both read-only mounts are writable from the container.pre-existing, correctness.pre-existing, correctness.Pre-existing findings, not filed
GOVERNANCE.md:347lists "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