feat: port upstream #1225 (Dockerfile metadata), #1078 (feature build secrets), #1241 (up --platform)

These three upstream PRs interleave in the up/build feature paths, so they land
together.

#1225 — preserve a user Dockerfile's `LABEL devcontainer.metadata`: the parser
now captures LABEL instructions (Dockerfile.StageLabels), and build/up merge the
Dockerfile-declared metadata into the composed label so the CLI's own stamped
label no longer clobbers the user's entries.

#1078 — build secrets in features: FeatureBuildOptions gains Secrets, forwarded
to the feature-install image build (buildx `--secret id=KEY,env=KEY`) and mounted
into each feature-install RUN as `--mount=type=secret,id=KEY` (new
DockerfileBuilder.RunWithMounts), so a Feature's install.sh can read
/run/secrets/KEY. Threaded from --secrets-file at every up/build call site;
gated on buildx. Compose feature secrets stay unsupported (compose build does
not forward --secret).

#1241 — `devcontainer up --platform`: new flag, and for image-based configs the
platform is derived from a `--platform` in runArgs when the flag is unset, then
used to pull (EngineClient.PullImagePlatform) and feature-build the image for the
platform it will run on (e.g. amd64 forced via runArgs on an arm64 host).

Tests added for each; the flag inventory is updated for up --platform.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aledbf

docs/parity/cli-flags-inventory.yaml

@@ -65,6 +65,9 @@ commands:
         choices: [all, detect, none]
         default: detect
         description: "Availability of GPUs in case the dev container requires any."
+      platform:
+        type: string
+        description: "Target platform (e.g. linux/amd64). Used to resolve, pull and build the image; overrides a --platform in runArgs."
       mount-workspace-git-root:
         type: boolean
         default: true

internal/cli/build.go

@@ -348,6 +348,10 @@ func (r *buildRunner) buildDockerfile(ctx context.Context, cfg *config.DevContai
 	}
 	baseMetadata := imagemeta.ReadMetadataFromLabels(baseLabels, logger)
 	metadata := append([]imagemeta.Entry{}, baseMetadata...)
+	// Preserve a `LABEL devcontainer.metadata` declared in the user's Dockerfile
+	// (#1225): the CLI stamps its own computed metadata label below, which would
+	// otherwise clobber the user's entries on the built image.
+	metadata = append(metadata, imagemeta.ReadMetadataFromLabels(prep.Parsed.StageLabels(stageName), logger)...)
 	if len(cfg.Features) == 0 {
 		metadata = append(metadata, configToMetadataEntry(cfg))
 	}
@@ -442,6 +446,7 @@ func (r *buildRunner) buildDockerfile(ctx context.Context, cfg *config.DevContai
 	if len(cfg.Features) > 0 {
 		baseImageName := imageNames[0]
 		return extendImageWithFeatures(ctx, logger, dockerClient, engine, baseImageName, cfg.Features, useBuildx, imageNames, &FeatureBuildOptions{
+			Secrets:                     buildSecretsFromFile(opts.secretsFile),
 			OverrideFeatureInstallOrder: cfg.OverrideFeatureInstallOrder,
 			NoCache:                     opts.noCache,
 			CacheFrom:                   opts.cacheFrom,
@@ -512,6 +517,7 @@ func (r *buildRunner) buildImage(ctx context.Context, cfg *config.DevContainer,
 			featureImageNames = []string{folderImageName(resolvePath(opts.workspaceFolder)) + "-features"}
 		}
 		return extendImageWithFeatures(ctx, logger, dockerClient, engine, cfg.Image, cfg.Features, useBuildx, featureImageNames, &FeatureBuildOptions{
+			Secrets:                     buildSecretsFromFile(opts.secretsFile),
 			OverrideFeatureInstallOrder: cfg.OverrideFeatureInstallOrder,
 			NoCache:                     opts.noCache,
 			CacheFrom:                   opts.cacheFrom,
@@ -545,6 +551,7 @@ func (r *buildRunner) buildImage(ctx context.Context, cfg *config.DevContainer,
 
 		if len(cfg.Features) > 0 {
 			return extendImageWithFeatures(ctx, logger, dockerClient, engine, cfg.Image, cfg.Features, useBuildx, featureImageNames, &FeatureBuildOptions{
+				Secrets:                     buildSecretsFromFile(opts.secretsFile),
 				OverrideFeatureInstallOrder: cfg.OverrideFeatureInstallOrder,
 				NoCache:                     opts.noCache,
 				CacheFrom:                   opts.cacheFrom,
@@ -794,6 +801,7 @@ func (r *buildRunner) buildCompose(ctx context.Context, cfg *config.DevContainer
 			imageNames = []string{baseImageName + "-features"}
 		}
 		return extendImageWithFeatures(ctx, logger, dockerClient, engine, baseImageName, cfg.Features, useBuildx, imageNames, &FeatureBuildOptions{
+			Secrets:                     buildSecretsFromFile(opts.secretsFile),
 			OverrideFeatureInstallOrder: cfg.OverrideFeatureInstallOrder,
 			NoCache:                     opts.noCache,
 			CacheFrom:                   opts.cacheFrom,

internal/cli/feature_install.go

@@ -33,13 +33,18 @@ type FeatureBuildOptions struct {
 	NoCache bool
 	// HostSub, when set, resolves ${localEnv:…}/${localWorkspaceFolder}/… in each
 	// Feature's containerEnv/mounts — same as the config's own substitution.
-	HostSub                *config.HostSubContext
-	CacheFrom              []string
-	CacheTo                string
-	Labels                 []string
-	Platform               string
-	Push                   bool
-	Output                 string
+	HostSub   *config.HostSubContext
+	CacheFrom []string
+	CacheTo   string
+	Labels    []string
+	Platform  string
+	Push      bool
+	Output    string
+	// Secrets are Docker build secrets ("KEY=VALUE") forwarded to the
+	// feature-install image build as buildx `--secret id=KEY,env=KEY`, so a
+	// Feature's install.sh can use `RUN --mount=type=secret` (#1078). Requires
+	// buildx; ignored by the legacy builder.
+	Secrets                []string
 	ContainerEnv           map[string]string
 	SkipFeatureAutoMapping bool
 	SkipPersistCustoms     bool
@@ -598,8 +603,14 @@ func extendImageWithFeatures(
 		configContainerEnv = fbOpts.ContainerEnv
 	}
 
+	// Build secrets are mounted into each feature-install RUN, but only when the
+	// build uses buildx (RUN --mount=type=secret + --secret both require BuildKit).
+	var secretIDs []string
+	if useBuildx && fbOpts != nil {
+		secretIDs = buildSecretIDs(fbOpts.Secrets)
+	}
 	buildInfo := imagemeta.GenerateExtendImageBuild(
-		baseImage, featureSets, metadata, containerUser, remoteUser, useBuildx, configContainerEnv,
+		baseImage, featureSets, metadata, containerUser, remoteUser, useBuildx, configContainerEnv, secretIDs,
 	)
 
 	// Write the Dockerfile
@@ -640,6 +651,7 @@ func extendImageWithFeatures(
 		buildOpts.Platform = fbOpts.Platform
 		buildOpts.Push = fbOpts.Push
 		buildOpts.Output = fbOpts.Output
+		buildOpts.Secrets = fbOpts.Secrets
 	}
 
 	// Add BuildKit contexts — resolve relative paths to tmpDir

internal/cli/feature_tarball_test.go

@@ -27,11 +27,11 @@ func TestIsGitHubTarballURI(t *testing.T) {
 
 func TestIsPlainHTTPURL(t *testing.T) {
 	cases := map[string]bool{
-		"http://example.com/feat.tgz":   true,
-		"https://example.com/feat.tgz":  false,
-		"https://localhost:8080/x.tgz":  true, // localhost even over https
-		"http://localhost/x.tgz":        true,
-		"https://127.0.0.1:5000/x.tgz":  false, // only the literal "localhost" host is special
+		"http://example.com/feat.tgz":  true,
+		"https://example.com/feat.tgz": false,
+		"https://localhost:8080/x.tgz": true, // localhost even over https
+		"http://localhost/x.tgz":       true,
+		"https://127.0.0.1:5000/x.tgz": false, // only the literal "localhost" host is special
 	}
 	for u, want := range cases {
 		if got := isPlainHTTPURL(u); got != want {

internal/cli/helpers.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"encoding/json"
 	"fmt"
+	"strings"
 
 	"github.com/devcontainers/cli/internal/config"
 	"github.com/devcontainers/cli/internal/log"
@@ -89,3 +90,17 @@ func logDimensions(columns, rows int) *log.Dimensions {
 	}
 	return nil
 }
+
+// findPlatformArg extracts the target platform from runArgs, supporting both
+// "--platform=linux/amd64" and "--platform linux/amd64". Returns "" when absent.
+func findPlatformArg(runArgs []string) string {
+	for i, a := range runArgs {
+		if v, ok := strings.CutPrefix(a, "--platform="); ok {
+			return v
+		}
+		if a == "--platform" && i+1 < len(runArgs) {
+			return runArgs[i+1]
+		}
+	}
+	return ""
+}

internal/cli/metadata_interop_test.go

@@ -192,7 +192,7 @@ func TestMetadataInteropGoRoundTrip(t *testing.T) {
 	// Build the Dockerfile exactly as build.go does for the no-features case
 	// (base image + metadata label), but pin the base to `scratch` so the build
 	// needs no network.
-	info := imagemeta.GenerateExtendImageBuild("scratch", nil, entries, "root", "", false, nil)
+	info := imagemeta.GenerateExtendImageBuild("scratch", nil, entries, "root", "", false, nil, nil)
 	dockerfile := info.DockerfilePrefixContent + info.DockerfileContent
 
 	tmp := t.TempDir()

internal/cli/pure_helpers_test.go

@@ -70,13 +70,13 @@ func TestHighestSatisfyingTag(t *testing.T) {
 
 func TestMajorOf(t *testing.T) {
 	cases := map[string]string{
-		"":            "",
-		"1.2.3":       "1",
-		"2":           "2",
-		"0.5.0":       "0",
-		"not-semver":  "",
-		"10.20.30":    "10",
-		"v3.1.0":      "3", // semver tolerates a leading v
+		"":           "",
+		"1.2.3":      "1",
+		"2":          "2",
+		"0.5.0":      "0",
+		"not-semver": "",
+		"10.20.30":   "10",
+		"v3.1.0":     "3", // semver tolerates a leading v
 	}
 	for in, want := range cases {
 		if got := majorOf(in); got != want {
@@ -423,3 +423,24 @@ func TestIsBareVersion(t *testing.T) {
 		}
 	}
 }
+
+// TestFindPlatformArg covers #1241: extracting --platform from runArgs in both
+// "--platform=X" and "--platform X" forms.
+func TestFindPlatformArg(t *testing.T) {
+	cases := []struct {
+		args []string
+		want string
+	}{
+		{[]string{"--platform=linux/amd64"}, "linux/amd64"},
+		{[]string{"--platform", "linux/arm64"}, "linux/arm64"},
+		{[]string{"--cap-add=SYS_PTRACE", "--platform=linux/amd64", "--rm"}, "linux/amd64"},
+		{[]string{"--rm"}, ""},
+		{nil, ""},
+		{[]string{"--platform"}, ""}, // dangling flag, no value
+	}
+	for _, tc := range cases {
+		if got := findPlatformArg(tc.args); got != tc.want {
+			t.Errorf("findPlatformArg(%v) = %q, want %q", tc.args, got, tc.want)
+		}
+	}
+}

internal/cli/secrets.go

@@ -43,3 +43,29 @@ func secretValuesFromFile(path string) []string {
 	}
 	return values
 }
+
+// buildSecretsFromFile reads build secrets ("KEY=VALUE") from a --secrets-file
+// path, or nil when unset/unreadable (a read error is non-fatal — the build
+// proceeds without secrets, matching the main build path).
+func buildSecretsFromFile(path string) []string {
+	if path == "" {
+		return nil
+	}
+	secrets, err := readSecretsFile(path)
+	if err != nil {
+		return nil
+	}
+	return secrets
+}
+
+// buildSecretIDs extracts the secret id (the KEY of each "KEY=VALUE") so it can
+// be mounted into a feature-install RUN as --mount=type=secret,id=KEY.
+func buildSecretIDs(secrets []string) []string {
+	ids := make([]string, 0, len(secrets))
+	for _, s := range secrets {
+		if i := strings.IndexByte(s, '='); i > 0 {
+			ids = append(ids, s[:i])
+		}
+	}
+	return ids
+}

internal/cli/up.go

@@ -69,6 +69,7 @@ type upOpts struct {
 	workspaceMountConsistency   string
 	updateRemoteUserUIDDefault  string
 	gpuAvailability             string
+	platform                    string
 	defaultUserEnvProbe         string
 	containerSessionDataFolder  string
 	skipFeatureAutoMapping      bool
@@ -129,6 +130,7 @@ func newUpCmd() *cobra.Command {
 	f.String("container-system-data-folder", "", "")
 	f.StringVar(&opts.workspaceMountConsistency, "workspace-mount-consistency", "cached", "Mount consistency.")
 	f.StringVar(&opts.gpuAvailability, "gpu-availability", "detect", "GPU availability (all|detect|none).")
+	f.StringVar(&opts.platform, "platform", "", "Target platform (e.g. linux/amd64). Used to resolve, pull and build the image; overrides a --platform in runArgs.")
 	f.StringVar(&opts.defaultUserEnvProbe, "default-user-env-probe", "loginInteractiveShell", "Env probe type.")
 	f.StringVar(&opts.updateRemoteUserUIDDefault, "update-remote-user-uid-default", "on", "UID update default.")
 	f.BoolVar(&opts.expectExistingContainer, "expect-existing-container", false, "Fail if no existing container is found.")
@@ -764,6 +766,8 @@ func (r *upRunner) fromDockerfile(ctx context.Context, cfg *config.DevContainer,
 	if baseInspect, inspErr := engine.InspectImage(ctx, baseImage); inspErr == nil && baseInspect.Config != nil {
 		metadata = append(metadata, imagemeta.ReadMetadataFromLabels(baseInspect.Config.Labels, logger)...)
 	}
+	// Preserve a `LABEL devcontainer.metadata` from the user's Dockerfile (#1225).
+	metadata = append(metadata, imagemeta.ReadMetadataFromLabels(prep.Parsed.StageLabels(stageName), logger)...)
 	metadata = append(metadata, imagemeta.Entry{RemoteUser: cfg.RemoteUser, ContainerUser: cfg.ContainerUser})
 	metadataLabel := imagemeta.GenerateMetadataLabel(metadata)
 
@@ -808,6 +812,7 @@ func (r *upRunner) fromDockerfile(ctx context.Context, cfg *config.DevContainer,
 	// Extend with features if any
 	if len(cfg.Features) > 0 {
 		names, err := extendImageWithFeatures(ctx, logger, dockerClient, engine, imageName, cfg.Features, useBuildx, nil, &FeatureBuildOptions{
+			Secrets:                     buildSecretsFromFile(opts.secretsFile),
 			OverrideFeatureInstallOrder: cfg.OverrideFeatureInstallOrder,
 			FeaturesBasePath:            filepath.Dir(cfg.ConfigFilePath),
 			SkipFeatureAutoMapping:      opts.skipFeatureAutoMapping,
@@ -837,11 +842,19 @@ func (r *upRunner) fromImage(ctx context.Context, cfg *config.DevContainer, load
 		return "", fmt.Errorf("no image specified in devcontainer.json")
 	}
 
+	// Target platform: the --platform flag wins, else a --platform in runArgs, so
+	// the image is pulled and (feature-)built for the platform it will run on —
+	// e.g. an amd64 image forced via runArgs on an arm64 host (#1241).
+	platform := opts.platform
+	if platform == "" {
+		platform = findPlatformArg(cfg.RunArgs)
+	}
+
 	// Pull if needed
 	_, err := engine.InspectImage(ctx, cfg.Image)
 	if err != nil {
 		logger.Write(fmt.Sprintf("Pulling image %s...", cfg.Image), log.LevelInfo)
-		if pullErr := engine.PullImage(ctx, cfg.Image); pullErr != nil {
+		if pullErr := engine.PullImagePlatform(ctx, cfg.Image, platform); pullErr != nil {
 			return "", fmt.Errorf("pull image %q: %w", cfg.Image, pullErr)
 		}
 	}
@@ -850,6 +863,8 @@ func (r *upRunner) fromImage(ctx context.Context, cfg *config.DevContainer, load
 	imageName := cfg.Image
 	if len(cfg.Features) > 0 {
 		names, err := extendImageWithFeatures(ctx, logger, dockerClient, engine, cfg.Image, cfg.Features, useBuildx, nil, &FeatureBuildOptions{
+			Platform:                    platform,
+			Secrets:                     buildSecretsFromFile(opts.secretsFile),
 			OverrideFeatureInstallOrder: cfg.OverrideFeatureInstallOrder,
 			FeaturesBasePath:            filepath.Dir(cfg.ConfigFilePath),
 			SkipFeatureAutoMapping:      opts.skipFeatureAutoMapping,
@@ -1342,8 +1357,11 @@ func (r *upRunner) fromCompose(ctx context.Context, cfg *config.DevContainer, lo
 			}
 
 			// Generate feature Dockerfile content for compose injection
+			// No build secrets here: `docker compose build` does not forward
+			// --secret to the injected feature stage, so mounting them would break
+			// the build. Compose feature build secrets remain unsupported for now.
 			featureContent := imagemeta.GenerateExtendImageBuildForCompose(
-				baseStageName, featureSets, metadata, containerUser, remoteUser, nil,
+				baseStageName, featureSets, metadata, containerUser, remoteUser, nil, nil,
 			)
 			combinedDockerfile := string(dockerfileContent) + "\n" + featureContent
 
@@ -1412,6 +1430,7 @@ func (r *upRunner) fromCompose(ctx context.Context, cfg *config.DevContainer, lo
 
 				logger.Write(fmt.Sprintf("Installing features on compose service %s...", cfg.Service), log.LevelInfo)
 				names, extErr := extendImageWithFeatures(ctx, logger, dockerClient, engine, baseImageName, cfg.Features, useBuildx, nil, &FeatureBuildOptions{
+					Secrets:                     buildSecretsFromFile(opts.secretsFile),
 					OverrideFeatureInstallOrder: cfg.OverrideFeatureInstallOrder,
 					FeaturesBasePath:            filepath.Dir(cfg.ConfigFilePath),
 					SkipFeatureAutoMapping:      opts.skipFeatureAutoMapping,

internal/docker/dockerfile.go

@@ -94,6 +94,10 @@ func ExtractDockerfile(content string) *Dockerfile {
 				}
 			case *instructions.UserCommand:
 				st.Instructions = append(st.Instructions, Instruction{Instruction: "USER", Name: c.User})
+			case *instructions.LabelCommand:
+				for _, kv := range c.Labels {
+					st.Instructions = append(st.Instructions, Instruction{Instruction: "LABEL", Name: kv.Key, Value: trimQuotes(kv.Value)})
+				}
 			}
 		}
 		df.Stages = append(df.Stages, st)
@@ -106,6 +110,30 @@ func ExtractDockerfile(content string) *Dockerfile {
 	return df
 }
 
+// StageLabels returns the LABEL key/value pairs declared in the named build
+// stage (or the final stage when name is ""), with later labels overriding
+// earlier ones. Used to recover a user's `LABEL devcontainer.metadata` from the
+// Dockerfile so the CLI-stamped metadata label does not clobber it.
+func (d *Dockerfile) StageLabels(name string) map[string]string {
+	var st *Stage
+	if name != "" {
+		st = d.StagesByLabel[name]
+	}
+	if st == nil && len(d.Stages) > 0 {
+		st = &d.Stages[len(d.Stages)-1]
+	}
+	if st == nil {
+		return nil
+	}
+	labels := map[string]string{}
+	for _, ins := range st.Instructions {
+		if ins.Instruction == "LABEL" {
+			labels[ins.Name] = ins.Value
+		}
+	}
+	return labels
+}
+
 // syntaxVersion extracts the tag of a docker/dockerfile syntax directive
 // ("docker/dockerfile:1.4" -> "1.4", no tag -> "latest", other frontend -> "").
 func syntaxVersion(syntax string) string {