Ensuring repeatable devcontainer images in GitHub Codespaces

Answer the question directly

To guarantee that every Codespace created from the same devcontainer.json uses exactly the same base image, specify the image by its SHA‑256 digest instead of a mutable tag.

Confirmed facts

• GitHub Codespaces reads the image field (or the FROM line in a Dockerfile) and pulls the referenced image.
• When the value is a digest (e.g., mcr.microsoft.com/vscode/devcontainers/typescript-node:0-214@sha256:), the Docker daemon pulls the exact layer set identified by that hash, regardless of any later updates to the tag.
• Codespaces does not expose a setting to disable or alter its internal image‑caching mechanism; the cache key is derived from the contents of devcontainer.json, any Dockerfile, and declared build arguments.
• Changing anything that influences that cache key (e.g., updating a digest, modifying a build arg, or editing the Dockerfile) forces a fresh pull/build on the next Codespace creation.

Likely explanation (if you are not using a digest)

If you keep a mutable tag like node:18, Codespaces may reuse a previously cached layer for an indeterminate period. When the upstream tag is updated on Docker Hub, the cached layer can still be used, leading to subtle differences between otherwise identical configurations.

Steps to enforce a specific digest

1. Obtain the SHA‑256 digest of the image you want to lock. For example, run locally:

   docker pull mcr.microsoft.com/vscode/devcontainers/typescript-node:0-214
   docker inspect --format='{{index .RepoDigests 0}}' mcr.microsoft.com/vscode/devcontainers/typescript-node:0-214
   

   This returns something like mcr.microsoft.com/vscode/devcontainers/typescript-node:0-214@sha256:abcd1234….
2. Edit devcontainer.json and set the image field to that full digest string:

   {
     "name": "typescript-node",
     "image": "mcr.microsoft.com/vscode/devcontainers/typescript-node:0-214@sha256:abcd1234…",
     "forwardPorts": [3000],
     "postCreateCommand": "npm install"
   }
   

3. If you prefer to keep a Dockerfile, replace the FROM line with the same digest:

   FROM mcr.microsoft.com/vscode/devcontainers/typescript-node:0-214@sha256:abcd1234…
   

4. Commit the change to the repository. New Codespaces will now pull the exact image identified by the digest, guaranteeing repeatability.
5. To verify, after a Codespace starts, run inside the container:

   docker inspect --format='{{index .RepoDigests 0}}' $(docker ps -q)
   

   The output should match the digest you placed in devcontainer.json.

When you need to update the base image

When you intentionally want a newer base, repeat step 1 to obtain the new digest and update the field. This makes the change explicit and version‑controlled.

Missing diagnostic detail

Are you currently using only the image field in devcontainer.json, or are you relying on a Dockerfile to build the container? The answer determines whether you edit the image field or the FROM line.