Graduate Dev Container Lockfile from Preview to Stable

[brooke-hamilton]

Summary

This issue proposes making the Dev Container lockfile (devcontainer-lock.json) feature stable in the Dev Container CLI, transitioning it from its current preview (experimental) state. The lockfile enables reproducible builds and integrity verification by recording exact digests and checksums for all Features resolved by the CLI.

This is a tracking issue for devcontainers/spec#727.

Motivation

• Reproducibility: Builds always resolve to the same set of features, regardless of time or machine.
• Security & Integrity: Feature artifacts are verified; unexpected changes or tampering are detected and will fail the build.
• Reviewable diffs: Lockfiles make changes in feature dependencies transparent and easy to audit.

Proposed Changes

1. Enable lockfile by default: The CLI (devcontainer build and devcontainer up) will automatically create and update devcontainer-lock.json by default. Users will no longer need to enable this feature with an experimental flag.
2. Add --no-lockfile and --frozen-lockfile flags:
   • --no-lockfile disables all lockfile behavior for users who wish to opt out (matches npm/pnpm conventions).
   • --frozen-lockfile enforces exact lockfile matches and fails if the lockfile is missing or mismatched.
   • The legacy --experimental-lockfile and --experimental-frozen-lockfile flags will be deprecated and replaced by the new flags, with warnings provided.
3. No changes needed for other CLI commands: The update only affects build and up; commands like outdated, upgrade, etc., already use or write lockfiles without additional flags.

Out of Scope

• No changes to the actual lockfile file format or related property keys in devcontainer.json.

This change brings the CLI in line with modern package management tools for security and reproducibility while offering users flexibility to opt out.

Lockfile specification
CLI implementation tracking issue
CLI lockfile implementation PR #495
Community discussion #237