In a GitHub Codespaces devcontainer.json, in what order do the lifecycle commands run, and which should install the project's dependencies?
answer
- three finish creation, two repeat
- which ones a prebuild can run
- where user secrets first appear
- what the editor waits for
- string, array or object form
basics
~10 sonCreateCommand, updateContentCommand and postCreateCommand finish setup once; postStartCommand runs at every start and postAttachCommand at every attach. Source-dependent installs belong in updateContentCommand, which the editor waits for by default.
solid answer
~40 sThe order is `onCreateCommand`, `updateContentCommand`, `postCreateCommand` (the three that finish creating the container), then `postStartCommand` each time the container starts and `postAttachCommand` each time a tool attaches. The first two can run while a prebuild is made, so they see only repository and organization scoped secrets; `updateContentCommand` also reruns whenever the prebuild is refreshed with new content, which makes it the place to install dependencies from the checked-out source. `postCreateCommand` runs once the codespace is assigned to its user, so per-user setup goes there. `waitFor` defaults to `updateContentCommand`: the editor connects when that finishes, and `postCreateCommand` carries on in the background. A string runs through `/bin/sh`, an array runs without a shell, an object runs its entries in parallel, and a failing command skips every command after it.
code
json · 11 lines{
"image": "ghcr.io/acme/web-dev:2026-10",
"onCreateCommand": "./scripts/install-tools.sh",
"updateContentCommand": "./scripts/install-deps.sh",
"postCreateCommand": "./scripts/configure-user.sh",
"postStartCommand": {
"api": "./scripts/start-api.sh",
"web": "./scripts/start-web.sh"
},
"waitFor": "updateContentCommand"
}go deeper
Recall the five commands in order and which ones run once versus at every start or connection.
Explain why dependency installs belong in updateContentCommand, what waitFor waits for by default, and how string, array and object forms differ.
Move slow work into the commands a prebuild runs, keep secrets-dependent steps in postCreateCommand, and diagnose setup that silently stopped after a failing command.
Set the team's convention for what runs before the editor connects and what runs behind it, trading time-to-first-keystroke against the risk of developers working in a half-ready environment.
## The five commands A dev container's **lifecycle commands** are commands, written in `devcontainer.json`, that run inside the container at fixed points. They run from the workspace folder, after the source is mounted, so they can call scripts in the repository. | Command | When it runs | How often | Can use | |---|---|---|---| | `onCreateCommand` | First of three that finish creation, right after the container first starts | Once per container | Repository and organization scoped secrets only | | `updateContentCommand` | After `onCreateCommand`, when new content is available | At least once; cloud services rerun it to refresh prebuilt containers | Repository and organization scoped secrets only | | `postCreateCommand` | Last of the three, once the container is assigned to a user | Once per container | User-specific secrets and permissions | | `postStartCommand` | Each time the container starts successfully | Every start | User-specific secrets too | | `postAttachCommand` | Each time a tool attaches | Every connection | User-specific secrets too | The specification also defines `initializeCommand`, which runs on the host before anything else; for a cloud service such as Codespaces that host is in the cloud, not on the developer's machine. ## Why the split exists The first two commands exist so that a cloud service can do slow work **before** anyone asks for a codespace. A Codespaces prebuild creates a temporary codespace, runs setup up to and including `onCreateCommand` and `updateContentCommand`, and snapshots the result. Because no user is involved yet, those commands cannot rely on a user's personal secrets. `postCreateCommand` runs only when a real codespace is assigned to its user, so it is the first place personal credentials exist. Registry logins Codespaces builds from secrets are added after `onCreateCommand`, which is why pulling a private image there fails. The split is also what decides how long developers wait. A repository whose codespaces take eight minutes to start often has everything, from toolchain downloads to a full dependency install, in `postCreateCommand`. None of that can be prepared ahead of time, so every developer pays for all of it at every creation. Moving the same work into the first two commands lets it happen once, in advance. ## waitFor: when the editor connects `waitFor` names the command the editor waits for before connecting. Its default is `updateContentCommand`, so a developer lands in an editor whose dependencies are already installed, while `postCreateCommand` continues in the background. Moving work between `updateContentCommand` and `postCreateCommand` therefore changes what the developer waits for, and moving it into the first two commands lets a prebuild do it ahead of time. ## String, array or object - A **string** runs through `/bin/sh`, so `&&`, pipes and variable expansion work: `"./scripts/a.sh && ./scripts/b.sh"`. - An **array** runs the program directly **without a shell**: `["./scripts/a.sh", "--fast"]`; quotes and `$VARIABLES` are passed literally. - An **object** maps names to string or array commands and runs them **in parallel**; each must succeed for the step to succeed. ## Failures, rebuilds and restarts - If one lifecycle command fails, the commands after it are **skipped**: a failing `postCreateCommand` means `postStartCommand` and `postAttachCommand` never run. - Rebuilding a codespace's container reruns the commands from `onCreateCommand` onward, even when the image layers come from cache. - Stopping and starting a codespace reruns `postStartCommand` and, when the editor reconnects, `postAttachCommand`; the three creation commands do not run again. - Features can contribute their own lifecycle commands; at each hook those run before yours. - The codespace's creation log records each command's output, so it is the first place to look when setup stopped half way. ## Where each kind of work belongs 1. Toolchains and caches that do not depend on the current source: `onCreateCommand` (or, better, a feature or the image). 2. Installing dependencies from the repository's own files and incremental builds: `updateContentCommand`, so every prebuild refresh repeats it. 3. Anything needing the user's identity or personal secrets, and Git hooks (the repository is cloned before the container exists, so template hooks never reach it): `postCreateCommand`. 4. Starting background services such as the API and the front-end dev server: `postStartCommand`, because processes do not survive a stop. 5. Opening a preview or printing a hint for whoever connects: `postAttachCommand`.
- Why does a docker pull of a private image fail in onCreateCommand but work in postCreateCommand?Codespaces writes the registry login it builds from your registry secrets into `~/.docker/config.json` after `onCreateCommand` and before `postCreateCommand`, `postStartCommand` and `postAttachCommand`. A pull in `onCreateCommand` has no credentials yet, which is also why such pulls are unavailable while a prebuild is created. Move the pull to `postCreateCommand`.
- When would you change waitFor from its default?When the editor is useless until later setup finishes, set it to `postCreateCommand` so developers do not race a half-configured environment. When the first command already makes the editor usable, `onCreateCommand` lets people connect sooner while `updateContentCommand` continues behind them.
- How do you install Git hooks in a codespace?From a lifecycle command such as `postCreateCommand`. Codespaces clones the repository onto the host before the container exists, so anything in a Git template directory inside the image never reaches the clone; a script run after creation can install the hooks into it.
- postCreateCommand runs every time the codespace starts
- By default the editor waits for postCreateCommand to finish
- onCreateCommand can read the user's personal Codespaces secrets
- The array form runs its commands in parallel
- If one lifecycle command fails, the later ones still run