In GitHub Codespaces, a prebuild is ready yet new codespaces still spend minutes on setup: which devcontainer.json commands does a prebuild run, and which never?
answer
- a snapshot taken ahead of time
- an Actions workflow builds it
- stops before the user arrives
- no personal secrets inside
- triggers trade freshness for minutes
basics
~10 sA prebuild runs setup up to and including onCreateCommand and updateContentCommand in a temporary codespace, then snapshots it; postCreateCommand never runs there. Slow work left in postCreateCommand therefore still runs at every creation.
solid answer
~50 sA prebuild configuration pairs a branch with one `devcontainer.json`. A GitHub Actions workflow creates a temporary codespace, clones the repository, builds the image with its features, runs `onCreateCommand` and `updateContentCommand`, and stores a snapshot in each selected region. Creating a codespace deploys that snapshot on a fresh machine and runs only what remains: `postCreateCommand`, then `postStartCommand` and `postAttachCommand`. So user-independent work such as toolchains, dependency installs and a first build must move out of `postCreateCommand`; source-dependent steps go in `updateContentCommand`, which every prebuild update repeats. Prebuilds see Codespaces secrets at repository and organization level but never a user's own, which is why per-user steps stay in `postCreateCommand`. The trigger trades freshness for Actions minutes: Every push (the default), On configuration change, or Scheduled. Each run consumes Actions minutes, and each region and retained version is stored, and billed, separately.
go deeper
Recall that a prebuild is a snapshot made ahead of time by a workflow, and that setup left for postCreateCommand still runs when you create a codespace.
Explain which lifecycle commands run inside a prebuild, why personal secrets are unavailable there, and what the three triggers update on.
Move slow setup into the commands a prebuild runs, choose a trigger, regions and history for the team, and diagnose a missing Prebuild ready label.
Weigh prebuild freshness against Actions minutes and multi-region storage across many repositories, and decide which branches deserve a prebuild at all.
## What a prebuild is A **prebuild** is a ready-made snapshot of a codespace for one combination of repository, branch and `devcontainer.json` file. A **prebuild configuration**, set up in the repository's Codespaces settings, names that branch and file. When it is saved, and afterwards whenever its trigger fires, a GitHub-managed GitHub Actions workflow (listed as **Codespaces Prebuilds** in the Actions tab) creates a temporary codespace, performs setup, and stores a snapshot of the container. When someone creates a codespace, the snapshot is deployed on a fresh virtual machine and only the remaining steps run. Machine types with a prebuild available are labelled **Prebuild ready**. The docs suggest prebuilds once creation takes more than about two minutes. ## What runs ahead of time and what waits for the user | Step | In the prebuild | At codespace creation | |---|---|---| | Clone the repository, build the image and features | Yes | Already done in the snapshot | | `onCreateCommand` | Yes | Already done in the snapshot | | `updateContentCommand` | Yes, and again on every prebuild update | Already done in the snapshot | | `postCreateCommand` | **Never** | Yes | | `postStartCommand`, `postAttachCommand` | No | Yes | Two consequences follow. First, anything slow in `postCreateCommand` is paid by every developer, every time. Second, the prebuild runs with no user attached, so it can use **Codespaces secrets at repository or organization level** but **not user-level secrets**, and Docker-in-Docker pulls of private images are unavailable during prebuild creation because Codespaces adds registry logins only after `onCreateCommand`. ## Turning an eight-minute start into seconds 1. Read a creation log and time each step of setup. 2. Move user-independent tooling into features or `onCreateCommand`. 3. Move dependency installs and incremental builds that depend on the source into `updateContentCommand`, so every prebuild update repeats them against the latest commit. 4. Leave in `postCreateCommand` only what needs the user: personal credentials, Git identity, hooks. 5. Keep `waitFor` at its default, `updateContentCommand`, so the editor opens once the prebuilt dependencies are in place. 6. Test configuration changes from a test branch first: a broken change on a prebuild-enabled branch breaks the prebuild for everyone. Then confirm the effect. A codespace created from a prebuild says so: the web client shows that a prebuilt codespace was found, and inside the codespace `gh api /user/codespaces/$CODESPACE_NAME --jq .prebuild` returns `true`. Branches created from a prebuild-enabled branch usually get prebuilds as well, as long as their dev container configuration matches. ## Triggers, regions and template history | Trigger | Updates when | Trade-off | |---|---|---| | **Every push** (default) | Any push to the branch | Freshest, most Actions minutes | | **On configuration change** | `.devcontainer/devcontainer.json` or the Dockerfile its `build.dockerfile` names changes | Fewer runs; dependencies may be stale | | **Scheduled** | On a schedule you set | Runs only when you choose; may miss recent configuration changes | The configuration-change trigger does **not** fire for `devcontainer.json` files in subfolders of `.devcontainer`. Other settings: - **Regions**: by default prebuilds are created in every available region; restricting them to the regions developers use cuts storage. - **Template history**: how many prebuild versions to keep, from 1 to 5, default 2. Keeping only 1 means no prebuild for an older configuration. - **Failure notifications** for named users or teams, and **Disable prebuild optimization** under advanced options. ## What a prebuild costs Every workflow run consumes **GitHub Actions minutes**, from the included allowance or billed. Every stored prebuild is billed for **storage** the same way as a codespace's storage, once per region and per retained version: four regions with two versions kept means up to eight stored prebuilds. Running out of Actions spending limit makes prebuild workflows fail. ## When the prebuild is stale or missing - Only one workflow runs at a time per configuration; queued pushes collapse to the latest, except that a configuration change runs at once. - If the latest run failed, **prebuild optimization** falls back to the previous prebuild for the same repository, branch and file, which may lag the branch; disabling it creates codespaces without a prebuild instead. - A branch whose configuration differs from its prebuild-enabled base branch loses prebuilds. - Repositories over 32 GB get no prebuilds for 2-core and 4-core machines.
- Why might a prebuild-enabled branch show no Prebuild ready label?The prebuild configuration may not cover that branch or your region; a push that changed the dev container configuration may still be rebuilding the prebuild; or recent runs that changed the configuration failed. A branch whose configuration differs from its prebuild-enabled base also loses prebuilds, and repositories over 32 GB have none for 2-core and 4-core machines.
- What does prebuild optimization do when the latest prebuild workflow fails?By default, Codespaces falls back to the previous prebuild for the same repository, branch and configuration file, keeping creation fast but possibly behind the branch. A repository administrator can select Disable prebuild optimization, so codespaces are created without a prebuild while the latest run has failed or is still running.
- How do you cut a prebuild's Actions and storage spend without giving it up?Switch from Every push to On configuration change or Scheduled, accepting that dependencies may need updating after creation; restrict prebuilds to the regions developers actually use; and lower Template history toward 1, at the price of no prebuild for older configurations. Each region and each retained version is stored and billed separately.
A prebuild is a kitchen that preps before the order arrives: stock, chopping and par-cooking (onCreateCommand, updateContentCommand) are done in advance, but plating for a particular diner (postCreateCommand, with that person's own secrets) waits until someone orders, and whatever was left on the plating station is still done while that diner waits.
- A prebuild runs postCreateCommand so the codespace is fully ready
- Prebuilds can use each developer's personal Codespaces secrets
- On configuration change also fires for devcontainer.json files in .devcontainer subfolders
- Prebuilds cost nothing because GitHub runs them outside your Actions usage
- One stored prebuild serves every region automatically