Skip to content

Document a Windows Devcontainer Launch With HOME and USERPROFILE Set - #3859

Merged
ptr727 merged 11 commits into
developfrom
docs/devcontainer-windows-launch
Nov 4, 2026
Merged

ptr727 merged 11 commits into
developfrom
docs/devcontainer-windows-launch

Conversation

@ptr727

@ptr727 ptr727 commented Nov 4, 2026 •

Copy link
Copy Markdown
Owner

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

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

…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.
Copilot AI lite review requested due to automatic review settings November 4, 2026 06:05
@ptr727

ptr727 commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head 1bdd608857fc93e879a8bc3baf280e9641764ccc, the content this pull request carries at that commit against develop, and it recorded 3 findings.

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread docs/devcontainer.md Resolved
Comment thread docs/devcontainer.md Resolved
A local pass found the evidence sentence read as one start, and the conditions omitted the gitconfig the container copies.
@codecov

codecov Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.31%. Comparing base (c86ee86) to head (af6fb6a).

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           
Flag Coverage Δ
python-3.13 83.31% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ptr727

ptr727 commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head c94ba31843c863e0d3dd974b1eef4813aa31c19a, the content this pull request carries at that commit against develop, and it recorded 2 findings.

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.
@ptr727

ptr727 commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head 2145758e65b9ba0ce885562785280e6d62dc386f, the content this pull request carries at that commit against develop, and it recorded 1 finding.

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.
@ptr727

ptr727 commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head af6fb6af907e2aa983b7c792544714766c491456, the content this pull request carries at that commit against develop, and it recorded 1 finding.

@ptr727
ptr727 merged commit 60dd068 into develop Nov 4, 2026
13 checks passed
@ptr727
ptr727 deleted the docs/devcontainer-windows-launch branch November 4, 2026 07:03
ptr727 added a commit that referenced this pull request Nov 4, 2026
…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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants