feat(workflows): add devcontainer lockfile integrity check

[katriendg]

Committed devcontainer-lock.json to source control and added a reusable CI workflow that validates lockfile integrity during PR validation. This closes a supply-chain gap where devcontainer features were declared in devcontainer.json without pinning to specific OCI digests, making builds non-reproducible and vulnerable to upstream tag mutation.

Description

DevContainer Lockfile

Added .devcontainer/devcontainer-lock.json pinning all six devcontainer features (azure-cli, git, github-cli, node, powershell, python) to exact versions with OCI SHA-256 digests. The lockfile follows the devcontainer lockfile spec, providing reproducible builds and supply-chain integrity verification.

Lockfile Integrity Workflow

Created .github/workflows/devcontainer-lockfile-check.yml as a reusable workflow with three-layer validation:

• Lockfile existence — fails fast with exit 1 if devcontainer-lock.json is absent
• SHA-256 integrity — validates that every feature entry has resolved and integrity fields with sha256: prefix via jq filtering
• Feature coverage — uses case-normalized comm -23 set difference to detect features in devcontainer.json missing from the lockfile

The workflow uses set -euo pipefail, SHA-pinned actions/checkout, persist-credentials: false, and minimized contents: read permissions. A soft-fail input allows controlled override for non-blocking usage.

PR Validation Integration

Wired devcontainer-lockfile-check.yml into pr-validation.yml with soft-fail: false for strict enforcement. The job runs in parallel with other security checks, positioned before workflow-permissions-check.

Change-Log Categorization

Updated devcontainer-change-log.yml to categorize devcontainer-lock.json as "Lockfile | Medium" priority, distinguishing the generated artifact from the "High" priority source configuration.

Documentation

Updated three documentation pages to cover the new lockfile and validation workflow for different audiences.

• Added DevContainer Features: Lockfile Integrity section to docs/security/dependency-pinning.md with validation rules table, lockfile format example, and regeneration guidance
• Added Lockfile section to docs/customization/environment.md explaining purpose, rebuild-regenerate-commit workflow, and CI enforcement
• Updated docs/architecture/workflows.md with new workflow entries in support and validation tables, Mermaid security subgraph, and job mapping table

Related Issue(s)

Fixes #1873

Type of Change

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Testing

• npm run lint:md — Passed (214 files, 0 errors)
• npm run spell-check — Passed (351 files, 0 issues)
• npm run lint:frontmatter — Passed (0 errors, 0 warnings)
• npm run validate:skills — Passed (22 skills, 0 errors)
• npm run lint:md-links — Passed (all links valid)
• npm run lint:ps — Passed (all PowerShell files clean)
• npm run plugin:generate — Passed (13 plugins generated, 0 errors)
• npm run docs:test — Passed (7 suites, 102 tests)
• Security analysis: no sensitive data exposure, no dependency vulnerabilities, no privilege escalation concerns detected. Workflow uses SHA-pinned actions, minimized permissions, persist-credentials: false, and strict bash mode.
• Manual testing was not performed.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used /prompt-analyze to review contribution (N/A — no AI artifact changes)
• Addressed all feedback from prompt-builder review (N/A — no AI artifact changes)
• Verified contribution follows common standards and type-specific requirements (N/A — no AI artifact changes)

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate
• Docusaurus tests: npm run docs:test

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege (N/A — no security scripts modified)

Additional Notes

• The lockfile is generated by the devcontainer tooling during container build. Contributors modifying devcontainer.json features must rebuild the container and commit the updated lockfile alongside their changes.
• The soft-fail input on the reusable workflow enables non-blocking usage for repositories that want to adopt lockfile validation incrementally.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.85%. Comparing base (a847cfa) to head (e1f2503).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1874      +/-   ##
==========================================
+ Coverage   80.82%   80.85%   +0.03%     
==========================================
  Files         117      115       -2     
  Lines       19095    18828     -267     
==========================================
- Hits        15433    15224     -209     
+ Misses       3662     3604      -58     

Flag	Coverage Δ
pester	84.64% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Dependency Review — All Checks Passed ✅

This PR adds supply-chain hardening via a devcontainer lockfile and a reusable integrity-check workflow. No new external dependencies are introduced.

SHA Pinning Compliance

File	Reference	Status
.github/workflows/devcontainer-lockfile-check.yml	actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2	✅ SHA-pinned

New Dependencies

None. The devcontainer-lock.json pins the six existing devcontainer features (azure-cli, git, github-cli, node, powershell, python) to exact OCI SHA-256 digests — it does not introduce new features or packages.

Devcontainer / Setup Alignment

No new tools added to either environment. copilot-setup-steps.yml is unaffected; the lockfile covers integrity pinning of existing features only. No synchronization gap.

License Compatibility

No externally licensed packages introduced. All referenced artifacts are from ghcr.io/devcontainers/features/, which are MIT-licensed devcontainer features already in use.

Lockfile Integrity

All six feature entries carry both resolved (OCI digest reference) and integrity (sha256: prefix) fields, consistent with the devcontainer lockfile spec.

---

All dependency-review safety checks pass. No action required from a dependency perspective.

Generated by Dependabot PR Review for issue #1874 · sonnet46 1.1M

[chaosdinosaur]

Nice work — the workflow has solid supply-chain hygiene: SHA-pinned actions/checkout with persist-credentials: false, least-privilege permissions: contents: read, set -euo pipefail, and correctly pre-sorted comm inputs for the coverage diff. Approving. Three non-blocking follow-ups for a later pass: (1) devcontainer.json is comment-free today so jq parses it fine, but it is spec-permitted JSONC — consider a guard that emits a clear error if a future comment breaks the parse; (2) the coverage check compares feature keys but not the version field, so a version bump in config with a stale lockfile digest passes silently — consider comparing versions; (3) comm -23 flags config-but-not-lock only — a comm -13 pass would also catch orphaned lock entries. The remaining BLOCKED state looks like branch protection / a required reviewer rather than a code issue.

[WilliamBerryiii]

LGTM ... just one follow-up item given I've been trying to extract all the embedded scripting so we can test stuff.

[bindsi]

Automated batch review: no actionable findings. The devcontainer lockfile integrity workflow, committed lockfile, and documentation updates look sound.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
actions/actions/checkout	de0fac2e4500dabe0009e67214ff5f5447ce83dd	🟢 5.9	Details Check Score Reason Code-Review 🟢 10 all changesets reviewed Binary-Artifacts 🟢 10 no binaries found in the repo Maintained ⚠️ 2 3 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 2 Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Fuzzing ⚠️ 0 project is not fuzzed Pinned-Dependencies 🟢 3 dependency not pinned by hash detected -- score normalized to 3 License 🟢 10 license file detected Packaging ⚠️ -1 packaging workflow not detected Signed-Releases ⚠️ -1 no releases found Security-Policy 🟢 9 security policy file detected SAST 🟢 8 SAST tool detected but not run on all commits Branch-Protection 🟢 5 branch protection is not maximal on development and all release branches

Scanned Files

• .github/workflows/devcontainer-lockfile-check.yml

[bindsi]

Approved: the devcontainer lockfile integrity workflow, tests, and documentation remain consistent after re-review. No actionable issues found.

[bindsi]

Approved: the devcontainer lockfile integrity workflow, tests, and documentation remain consistent after re-review. I did not find actionable issues.