Will your next build be faster, and why did your change not ship? When build caching is enabled on your instance, an unchanged rebuild reuses layers from your service's previous build instead of redoing every step — and when a rebuild surprises you, the cause is usually invalidation (or its absence), not the cache rewriting your code.
Build caching is enabled per instance by the operator and may be withdrawn automatically; do not assume it is on. Everything below describes how caching behaves where it is enabled.
What is cached
Each service has its own layer cache in the instance registry, holding the layers from that service's previous build. The cache is rolling: only the latest generation is kept, so there is no history to browse or prune, and one service's layers are never visible to another.
A build whose cache is warm restores those layers before running, so steps
whose inputs are unchanged show as CACHED in the build log instead of
re-executing. A first build, or one whose cache is missing, simply builds
everything — a missing or corrupt cache never fails a build.
When a build imports the cache
A normal deploy on an enabled instance imports the service's stored layers and then exports a fresh cache from the layers it just built, keeping the rolling generation current. Two cases skip the import:
- A deploy requested with cache clearing rebuilds every layer and still exports a fresh cache afterwards. See clearing the cache.
- With caching disabled on the instance, builds run exactly as if the feature did not exist: no restore, no export, and cache-clearing requests change nothing.
What invalidates the cache
| Trigger | What happens |
|---|---|
| New source commit | Changed files rebuild from the first affected layer down |
| Dockerfile or build context change | Edited instructions and everything after them re-execute (stock BuildKit layer semantics) |
| Native build environment values change | The operator tracks an opaque revision of the effective environment and folds it into the env-dependent build step, so a values-only change re-runs that step even at a fixed commit |
| Base image update | A new base digest invalidates every layer above it |
| Cache clearing requested | The deploy skips the import and rebuilds all layers |
Secret contents alone never invalidate a layer: BuildKit does not fold secret mounts into cache keys, which is why the native environment needs its explicit revision above. Raw secret values never appear in the generated build steps.
Bounds
The cache is bounded so it can only ever cost time, never correctness or a failed deploy. Cache transfers carry their own timeout far below the build's deadline, so a hung registry transfer costs minutes rather than the build. Cache volumes are size-bounded, and only one rolling generation exists per service — there is no unbounded growth to manage and nothing for you to clean up besides requesting a clear rebuild.
What caching never changes
- The source built. Every build clones fresh; the cache holds layers, not source checkouts.
- Runtime environment values. The cache wraps the build only. What your running container sees still comes from the pushed image plus its own environment.
- Image-backed deploys. Deploying a prebuilt image runs no build, so there is nothing to cache or clear.
- Build outcomes. A cache hit reproduces exactly the image the cache was built from. Caching affects speed, never results.
Observing and clearing
Your build log is the only cache signal: reused steps print CACHED, and a
failed best-effort cache step surfaces as a bex: build cache step failed
line without failing the build. Deploy responses carry no cache fields, and
there is no API that reports whether caching is on — if every step rebuilds,
the instance may simply have it off.
To force a clean rebuild, clear the cache for one deploy from the CLI,
REST, GraphQL, or the dashboard; the next deploy after that reuses the fresh
cache normally. See How deploys work
for the clearing paths and Docker deploys for
stale-artifact recovery. Source pin: Bex 6f2975248.