Codespaces prebuild freshness limits after devcontainer changes

Prebuild Invalidation and Verification

Changes to the base image or the features array in devcontainer.json typically invalidate existing prebuilds because these modifications alter the resulting container image hash. When the underlying image definition changes, the snapshot is no longer a valid representation of the environment, triggering a new prebuild process if the configured trigger (such as a push to the tracked branch) is active.

Understanding the Freshness Gap

A critical distinction exists between the image state and the content state. Because updateContentCommand and postCreateCommand execute at runtime, a codespace may appear up-to-date regarding application code while running on a stale system image. This happens if a prebuild is reused despite changes to the base image, masking the staleness of system-level dependencies.

Verification Steps

There is currently no single "Freshness" indicator in the GitHub UI to confirm if a specific codespace instance used a current or stale prebuild. To verify the environment state, use the following methods:

• Inspect Image IDs: Run cat /proc/self/cgroup or check the container runtime logs to see if the image ID matches the most recent successful prebuild run.
• Version Check: Manually verify a package version that was specifically updated in the latest devcontainer.json change (e.g., node -v or python --version).
• Workflow Logs: Navigate to the Actions tab in your repository and review the prebuild workflow logs to confirm that a new image was successfully built and pushed following your last commit.

Regional and Machine Type Constraints

Prebuild availability is not guaranteed. If a specific region is experiencing capacity limits or if the selected machine type is unavailable for prebuild caching, GitHub may fall back to a full build from scratch. In these cases, the codespace will start slower, but it will be guaranteed to be fresh as it builds directly from the latest devcontainer.json.

Recommendation

To ensure consistency, verify your prebuild trigger settings in the repository's Codespaces configuration. If you are seeing stale environments, check if the prebuild is tracking the correct branch.

Diagnostic Detail Needed: Are you using a custom Dockerfile or a pre-defined image from a registry? (Custom Dockerfiles may require specific cache-busting strategies if the base image tag remains the same but the underlying image is updated).