Proposal: preserve Dockerfile devcontainer.metadata through CLI metadata composition

[RossBugginsNHS]

Attribution

Filed by Ross Buggins after interactive investigation and drafting assistance from GitHub Copilot. The content was reviewed and submitted by the author, not posted by an unattended bot.

Summary

This proposal requests that Dockerfile-declared devcontainer.metadata be preserved when the Dev Containers CLI computes the final effective metadata payload for Dockerfile-based build paths, including feature-enabled paths.

Motivation

The image metadata label mechanism appears intended to allow image authors to declare runtime-relevant dev container defaults in the image itself. In practice, current CLI build paths can drop user Dockerfile metadata from the final effective metadata label, which breaks that expectation.

Problem Statement

Expected

If a Dockerfile contains LABEL devcontainer.metadata=..., those metadata entries should participate in normal metadata merge/composition and remain present in the final effective metadata produced by the CLI.

Actual

In investigated CLI build paths, especially when features are involved, the final effective devcontainer.metadata can exclude metadata declared directly in the user Dockerfile.

Impact

This can silently remove runtime-critical settings declared in metadata, such as:

• mounts
• lifecycle hooks like postCreateCommand
• other merged configuration fields expected to survive extension/build wrapping

Proposed Semantics

The CLI should preserve Dockerfile-declared devcontainer.metadata as user intent and compose it with other metadata sources instead of dropping it.

Property / Behavior	Type	Description
Dockerfile devcontainer.metadata preservation	metadata merge behavior	Metadata declared in Dockerfile LABEL devcontainer.metadata=... should be included in the metadata set used to compute the final effective metadata payload.
Merge ordering	merge behavior	Dockerfile-declared user metadata should be preserved alongside base image metadata, feature metadata, and config-derived metadata.
Feature interaction	merge behavior	Feature metadata should continue to append/merge according to existing rules and should not erase user Dockerfile metadata entries.

Observed Reproduction Summary

1. docker build alone preserved user metadata.
2. devcontainer build without features could lose user metadata depending on base image metadata state.
3. devcontainer build with features consistently lost user metadata in the tested cases.

High-Probability Behavioral Gap

In the Dockerfile build flow, downstream metadata composition appears to use base image metadata as an input but not reliably merge metadata declared directly in the user Dockerfile into the final computed payload.

Desired Outcome

The final effective metadata should contain the composed result of:

1. base image metadata
2. user Dockerfile metadata
3. feature metadata
4. config-derived metadata

Implementation Evidence

Working implementation and regression tests are available here:

• RossBugginsNHS/devcontainers.cli PR Move settings and extensions properties to vscode namespace #1

If useful, I can provide a reduced reproduction and exact source-path notes from the CLI implementation.

Request For Feedback

Please confirm whether the intended spec/behavior is:

1. preserve Dockerfile-declared image metadata through CLI build composition, or
2. treat wrapper-generated metadata as authoritative even when it drops user Dockerfile metadata

My expectation is the first option, but I am looking for confirmation on intended merge semantics before treating this as fully settled behavior.