On-Create Phase
Early in-container hooks that create container-local state — user-home caches, CLI configuration, directories — before repository-driven setup runs.
- Kind
- Lifecycle
- Domain
- Environment & Tooling
- Applies at
.devcontainer/lifecycle/on-create.d/- Status
- Stable
- Source · managed
.devcontainer/lifecycle/on-create.d/README.md
01 Defines
The onCreateCommand phase: scripts in on-create.d/ that run inside the container when it is first created, establishing container-local state that later phases consume.
02 Applies when
- A user-home cache or configuration file must exist before dependencies are restored.
- A later phase consumes a directory or CLI setting that does not depend on workspace content.
03 Boundaries
- Anything driven by project manifests or source files belongs in update-content or post-create.
- Shell or profile customisation that can wait belongs in post-create.
- Interactive prompts that need a developer present are out of scope.
Expected behaviour
- 01Scripts run inside the container, once on creation, before the content-focused phases.
- 02Scripts are idempotent so they remain safe to rerun while troubleshooting.
- 03The phase holds only setup that later phases depend on.
Behaviour#
On-create is the first phase inside the container. Its job is to lay down
container-local state — things that live under $HOME or in tool
configuration — so that the repository-driven phases that follow find them in
place.
The distinction from
Update-Content Phase
is the input. On-create
work depends on the container; update-content work depends on the repository’s
files. A Terraform plugin cache directory is on-create; terraform init against
the checked-in roots is not.
Good uses
- Creating
$HOME/.cache/bazeland writing~/.bazelrcfor a container-local disk cache - Creating
$HOME/.terraform.d/plugin-cachefor later provider caching - Writing a baseline
~/.npmrcthat sets a registry before dependencies install
Avoid
npm install,pnpm install,dotnet restore, orhugo mod tidy- Shell or profile customisation that can wait until final setup
- SSO login flows and other prompts that need a developer
Examples#
#!/usr/bin/env bash
set -euo pipefail
mkdir -p "$HOME/.cache/bazel"
printf '%s\n' "build --disk_cache=$HOME/.cache/bazel" > "$HOME/.bazelrc"
The script overwrites ~/.bazelrc rather than appending to it, so running it a
second time leaves the same file behind.
Connections