Configuring Codespaces Prebuilds in GitHub Actions

An unprebuilt Codespace does the full build on create, which is slow. This page configures prebuilds so the expensive stages are baked ahead of time for the branches developers open, and refreshed automatically when the base image or Features change.

Prerequisites

You need a repo with Codespaces enabled and admin access.

  • Codespaces enabled on the repository/org.
  • Admin access to configure prebuilds.
  • A committed .devcontainer/ config.

Prebuild prerequisitesYou need the prebuild config, target branches, refresh triggers, and a create check.Prebuild configrepo settingsBranchestarget key onesTriggerson config changeVerifyfast create

Step-by-Step Implementation

  1. Enable a prebuild for the branches developers open (repo Settings → Codespaces).
Settings -> Codespaces -> Set up prebuild -> choose branch + region
  1. Trigger on config changes so the prebuild never drifts.
Trigger: "On configuration change" (rebuilds when .devcontainer changes)
  1. Keep the config prebuild-friendly — heavy work in onCreateCommand.
{ "onCreateCommand": "npm ci", "remoteUser": "node" }
  1. Verify a new Codespace on that branch creates fast.

Create time by prebuildPrebuilds bake the expensive stages so a Codespace create is near-instant.No prebuild create118sPrebuild create20sPrebuild + warm caches12sillustrative create time

Common Pitfalls

Prebuild issues are stale prebuilds or heavy work outside onCreate.

Prebuild triageA triage path from slow creates to fast, current prebuilds.Is a prebuild set for the branch?NOConfigure oneDoes it rebuild on config change?YESHeavy work in onCreateCommandFast, current prebuilds

SymptomRoot CauseRemediation
Create is slow despite prebuildPrebuild not covering the branchAdd the branch to the prebuild
Prebuild uses a stale toolchainNot triggered on config changeTrigger on configuration change
Prebuild storage cost highToo many branches/regionsLimit to key branches/regions
Little speedupHeavy work in postCreateMove source-independent work to onCreate

Conclusion

Prebuilds convert a per-create wait into a shared, cached build. Configure them for the branches developers open, trigger a refresh on .devcontainer changes so they never drift, and put source-independent setup in onCreateCommand so the prebuild captures it. Creates then take seconds.

Cover and refreshPrebuilds cover key branches and refresh on config changes to stay current.Prebuild coversKey branchesBase + FeaturesonCreate stageRefresh onConfig changeFeature bumpSchedule

FAQ

Which branches should I prebuild? The ones developers actually open — usually the default branch and long-lived feature branches — not every push. Prebuilding everything wastes storage; prebuilding the branches people create Codespaces from gives the speedup where it matters.

How do prebuilds stay current with my config? Set the prebuild to trigger 'on configuration change' so it rebuilds whenever .devcontainer (the base image or Features) changes. That keeps the prebuilt image identical to a fresh build, so developers never get a stale toolchain.

Why isn't my prebuild speeding up create much? Because most of the setup is in postCreateCommand, which runs after the mount and isn't baked into the prebuild. Move source-independent work (tool installs, Feature setup) into onCreateCommand, which the prebuild captures, leaving only source-dependent installs for create time.