Cache mounts and build secrets: --mount=type=cache keeps downloads warm, --mount=type=secret keeps tokens out of layers

Cache mounts: keep the package cache warm across builds

Here is the frustrating loop every engineer hits: you move package-lock.json before COPY . . to optimize ordering, but the lockfile still changes on every dependency bump and you are back to a three-minute npm ci. Good ordering minimizes reruns; it cannot eliminate them. Layer caching is all-or-nothing per vertex: change one byte the RUN npm ci depends on and the whole step reruns cold, re-downloading every dependency. But a package manager already has its own internal cache (npm’s ~/.npm, Go’s /go/pkg/mod, pip’s ~/.cache/pip, apt’s /var/cache/apt) — and normally that cache lives inside the layer, so a layer cache miss throws it away too. RUN --mount=type=cache breaks that coupling: it mounts a persistent BuildKit-managed directory into the build that survives across builds independently of layer caching.

# syntax=docker/dockerfile:1
FROM node:22 AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

Now even when package-lock.json changes and the npm ci layer misses, the ~/.npm cache mount is still populated from prior builds, so npm re-uses already-downloaded tarballs and only fetches what is genuinely new. On a large monorepo this turns a ~3-minute cold npm ci into a ~25-second warm one; a Go service’s go mod download over a /go/pkg/mod cache mount drops from minutes to seconds. The cache mount is not in any layer — it never ships — and BuildKit serializes concurrent access with a sharing mode (default shared; use locked for tools that cannot tolerate concurrent writers, like some package databases).

Build secrets: a credential that touches no layer

The Hook’s failure is structural, not a mistake of forgetting an rm. ARG and ENV values are recorded in the image config and docker history; any command string that interpolates a secret is recorded verbatim; and every layer is immutable, so a later rm cannot remove bytes from an earlier layer — it only stacks a whiteout on top while the data sits readable in the layer below, shipped to anyone who pulls. RUN --mount=type=secret solves it at the root: BuildKit mounts the secret as a file (default /run/secrets/<id>) only for the duration of that one RUN, and it is never written to the layer, the config, or the history.

# syntax=docker/dockerfile:1
FROM node:22
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=secret,id=npmtoken \
    NPM_TOKEN=$(cat /run/secrets/npmtoken) \
    npm ci
# build with:  docker build --secret id=npmtoken,env=NPM_TOKEN .

The token is read from the mounted file inside the command, used by npm ci, and gone when the step ends. docker history shows the RUN with the --mount flag and no token. The published image carries nothing. You provide the value at build time from an env var (--secret id=npmtoken,env=NPM_TOKEN) or a file (--secret id=npmtoken,src=./token) — never as a build arg. The same mechanism delivers SSH agents (--mount=type=ssh) for private git deps without baking a key. The rule that prevents the whole class of incident: a credential needed only at build time goes through a secret mount; it never appears in ARG, ENV, or a command string.