Cutting Codespace Startup Time with Prebuild Images

The problem: minutes lost on every new Codespace

When a team adopts GitHub Codespaces, the first thing developers notice is the wait. A fresh Codespace pulls the base image, runs the Dockerfile in .devcontainer, installs dependencies, and only then becomes usable. On a moderately sized project that can take three to five minutes—multiplied by dozens of developers and frequent branch switches, the idle time adds up fast.

How prebuild images change the equation

GitHub Codespaces can build a prebuild image in the background and store it in the repository’s container registry. When a developer creates a new Codespace, the platform reuses that cached image instead of rebuilding from scratch. The result is a startup that often finishes in seconds.

The prebuild is triggered automatically on each push to the default branch (or on a schedule you define). The image is tagged with the commit SHA, so the environment always matches the source it was built from.

Configuring a prebuild – a worked example

Assume a Node.js project with a .devcontainer/Dockerfile that installs project dependencies via npm ci. Add a prebuild section to .devcontainer/devcontainer.json:

{
  "name": "Node App",
  "build": { "dockerfile": "Dockerfile" },
  "prebuild": {
    "enabled": true,
    "dockerfile": "Dockerfile",
    "context": ".",
    "cacheFrom": ["type=registry,ref=ghcr.io/{{owner}}/{{repo}}/prebuild:latest"],
    "cacheTo": ["type=registry,ref=ghcr.io/{{owner}}/{{repo}}/prebuild:latest,mode=max"]
  }
}

• enabled – turns the feature on.
• dockerfile and context – point to the same files used for a normal build.
• cacheFrom/cacheTo – tell BuildKit where to pull and push the cached layers (the ghcr.io registry is the default for GitHub‑hosted repositories).

Commit the change and push to the default branch. GitHub will start a background prebuild workflow (visible under the Codespaces tab → Prebuilds).

Verifying the gain

1. Open a terminal with the gh CLI authenticated to the organization (requires repo and codespace scopes).
2. Run gh codespace prebuilds --repo OWNER/REPO – this lists active prebuilds, their image tags, and the last build status.
3. Create a new Codespace from the UI or with gh codespace create --repo OWNER/REPO --branch main. The Codespaces UI shows a “Prebuild ready” badge and the start‑up log will report Using prebuilt image ….
4. Measure the elapsed time from clicking “Create” to the terminal prompt. Compare it with a baseline taken before the prebuild was enabled (you can repeat the same steps on a branch without the prebuild config).

Expected check: the first Codespace after a push should start in under 30 seconds on a typical Node.js stack, versus 2–4 minutes without a prebuild.

Trade‑offs and limitations

• Cost – each prebuild consumes GitHub Actions build minutes and stores an image in the container registry (storage billing applies). Excessive prebuilds on many branches can inflate the bill.
• Stale dependencies – if package-lock.json or a base image changes without a new prebuild, developers may get outdated packages. The cache is invalidated automatically when the Dockerfile, any file under .devcontainer/, or the referenced base image digest changes, but manual rebuilds are sometimes needed.
• Runner/region mismatch – prebuild images are built on the runner type and region defined for the repository. Creating a Codespace on a different runner (e.g., ARM vs. x86) will fall back to a full build.
• Large Dockerfiles – prebuilds accelerate the start but do not eliminate a long initial build; the first prebuild still takes the full Docker build time.

Actionable next steps

1. Add the prebuild block to your devcontainer.json (use the snippet above as a template).
2. Enable Codespaces for the repository if it isn’t already (Settings → Codespaces → Enable).
3. Push to the default branch and watch the Prebuilds page for the first successful run.
4. Run the gh codespace prebuilds command to confirm the image tag and build logs.
5. Benchmark a cold Codespace start before and after the change; document the time savings for the team.
6. Set a schedule (via the prebuild.schedule field) or a branch filter if you only need prebuilds on long‑lived branches, to keep costs predictable.

With a single configuration change and a few minutes of observation, you can turn a multi‑minute wait into a near‑instant developer environment—freeing the team to focus on code instead of container builds.