Docker Layer Caching Explained: Faster Image Builds in CI

Docker builds an image as a stack of cached layers. Order your Dockerfile so the parts that rarely change come first, and most builds reuse almost everything.

Each instruction in a Dockerfile produces a layer. Docker can reuse a layer from a previous build if its inputs are unchanged - but a single early change invalidates everything after it. Ordering is everything.

How layers are cached

Docker hashes each instruction and its inputs. If the hash matches a cached layer, it reuses it instead of re-running the step. The moment one layer’s inputs change, that layer and every layer below it are rebuilt - the cache is invalidated downward, not selectively.

Order for cache hits

Put stable instructions first and volatile ones last. Copy your dependency manifest and install dependencies *before* copying your application source, so a code change does not bust the dependency-install layer.

Cache-friendly ordering

COPY package*.json ./
RUN npm ci          # cached unless deps change
COPY . .            # changes often; only this layer rebuilds
RUN npm run build

Why CI often misses the cache

Ephemeral runners start with no local image cache each run.
No external cache backend configured, so nothing is restored.
Copying source before installing deps, invalidating deps every commit.
A changing build argument near the top of the file busting everything.

Caching across CI runs

Because ephemeral runners have no local cache, you need an external one: BuildKit’s registry-backed cache (--cache-from / --cache-to) stores layers in a registry so the next run restores them. Without that, every CI build is effectively a cold build.

Key takeaways

Each Dockerfile instruction is a layer; one change invalidates all below it.
Order stable steps first, volatile steps (source copy) last.
Install dependencies before copying app source for reliable hits.
Ephemeral CI needs an external (registry-backed) cache to hit at all.