Accelerate GitHub Codespaces with Prebuilds: A Step‑by‑Step Guide

Desired Outcome

Reduce the time it takes to launch a Codespace from several minutes to under 30 seconds by using prebuilds that cache the full devcontainer image.

Prerequisites

• Repository with write access or repository admin permissions.
• GitHub Codespaces enabled for the org/user.
• Working devcontainer.json (or Dockerfile) that builds successfully on a normal Codespace.
• GitHub Actions workflow permissions to read and write packages to ghcr.io.
• Secrets referenced in devcontainer.json (e.g., ${secrets.GH_TOKEN}) configured at the repo or org level.

Configuration Steps

1. Verify devcontainer.json

   {
     "name": "My Project",
     "image": "mcr.microsoft.com/vscode/devcontainers/base:ubuntu-22.04",
     "features": {
       "ghcr.io/devcontainers/features/node:1": {"version": "18"},
       "ghcr.io/devcontainers/features/python:1": {"version": "3.11"}
     },
     "postCreateCommand": "npm ci"
   }
   

   Ensure the image and features are compatible with the runner architecture (linux/amd64).

2. Create the prebuild workflow

   # .github/workflows/codespaces-prebuild.yml
   name: Codespaces Prebuild
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
     schedule:
       - cron: "0 0 * * 0"  # weekly
   jobs:
     prebuild:
       uses: github/codespaces/prebuild@v1
       with:
         image-name: ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}/codespaces/${{ github.ref_name }}:${{ github.sha }}
         devcontainer-path: .devcontainer
       secrets: inherit
   

   Place the file in .github/workflows. The workflow triggers on pushes, PRs, or a schedule and invokes the official prebuild action.

3. Commit and push to the default branch

   GitHub Actions will automatically run the prebuild job, building the image and pushing it to ghcr.io under a tag that includes the commit SHA.

4. Check prebuild status

   Navigate to Repository Settings > Codespaces > Prebuilds to view the latest prebuilds and their health. A green check indicates success.

5. Open a new Codespace

   When creating a Codespace from a branch that has a successful prebuild, VS Code will display a Prebuilt badge in the status bar. The container should start in <30 seconds.

Validation

• In the new Codespace, run node -v and python --version to confirm the tool versions match the devcontainer.json.
• Execute npm ci && npm test to ensure the project builds and tests run as expected.
• Inspect the Actions run for the prebuild job and confirm the image was pushed to the expected registry path.
• Optional: Pull the image locally and run docker history ghcr.io/.../codespaces/...:sha to verify layers correspond to devcontainer steps.

Rollback and Recovery

• To disable prebuilds, delete the workflow file or remove the prebuild job from it.
• In Repository Settings > Codespaces > Prebuilds, click Delete next to the prebuild you want to remove.
• When a prebuild is absent, creating a new Codespace will trigger an on‑demand build, which may take several minutes.
• If the prebuild fails, review the Actions log for errors such as build timeouts, missing secrets, or incompatible base images.
• Common fixes:
  • Increase the Actions job timeout (default 60 minutes).
  • Add missing secrets to the repo or org.
  • Ensure the base image supports the runner’s OS/architecture.

Common Pitfalls

• Prebuilds only rebuild when devcontainer.json or referenced files change. Manual triggers can be added with workflow_dispatch.
• Large images (>10 GB) may hit the GitHub Container Registry size limit. Use .dockerignore to slim down layers.
• GPU‑enabled devcontainers are currently not supported in prebuilds; verify the latest docs before using them.
• Prebuilds consume GitHub Actions minutes and package storage; monitor usage in the org billing dashboard.