GitHub Codespaces devcontainer.json image pinning across create and rebuild

What determines the resolved image digest during a Codespaces rebuild?

A rebuild re-resolves the tag from the registry. It does not reuse the digest resolved at creation time unless devcontainer.json specifies an immutable digest reference. Mutable tags are looked up on each lifecycle event that rebuilds the container image.

Likely explanation versus confirmed facts

The following reflects well-established devcontainer behavior:

• At creation, a tag such as mcr.microsoft.com/devcontainers/universal:2 is resolved to a SHA256 digest and cached for that session.
• On rebuild, the platform issues a new registry lookup. If the tag has been retargeted, the rebuild uses the new content.
• A digest-only URI (docker://registry/image@sha256:...) skips tag resolution and pins the exact content.

Treat the following as uncertain and verify against your current plan and region: whether intermediate caching layers persist across rebuilds, and how organization base-image policies interact with digest references. Policies may override or reject a pinned image, so the effective digest can differ from what is committed.

How to require digest pinning without client-side enforcement

1. Replace tag references in devcontainer.json with a digest-only URI, for example "image": "docker://ghcr.io/org/image@sha256:abc...".
2. Add a CI check that fails if devcontainer.json contains a bare tag without a digest, preventing regressions before they reach Codespaces.
3. If organization policies restrict base images, coordinate with the policy owner to allow the specific digest, or pin to an allowed base and layer your tooling with a Dockerfile.

Verification

• After creation, note the image ID from the Codespace creation log or run docker inspect --format '{{.Id}}' against the active container inside the Codespace terminal.
• Trigger a rebuild and repeat the inspection. If the ID changes, the tag was re-resolved; if it matches, the digest is pinned.

One detail would change the recommendation: do you have administrative control over the organization Codespaces policy? If not, digest pinning in the repository may be overridden by policy, and the fix requires a policy update rather than a devcontainer change.