Build secrets and SSH mounts · Docker & Containers

The default docker build has no way to pass secrets without exposing them in layers. BuildKit fixes this with RUN --mount and RUN --ssh.

The fix matters because the alternative is not “slightly less tidy”. A credential that reaches an image layer or an image config is in a content-addressed blob that you cannot edit, that has already been replicated to every node that pulled it, and that no amount of retagging or deleting will recall.

Build secrets (`--mount=type=secret`)

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
  npm ci

docker buildx build --secret id=npmrc,src=$HOME/.npmrc .

The secret file is mounted at /root/.npmrc (or wherever specified) during the RUN step. After the step, the secret file is gone. The layer produced by the step does not contain the secret.

Multiple secrets:

RUN --mount=type=secret,id=aws_key \
    --mount=type=secret,id=aws_secret \
  ./deploy.sh

Every option, and the defaults that catch people

The Dockerfile reference documents these fields on --mount=type=secret:

Field	Default	Notes
`id`	basename of `target`	The name the CLI must supply
`target` / `dst` / `destination`	`/run/secrets/` + `id`	Where the file appears
`env`	—	Mount as an environment variable instead of a file (Dockerfile frontend 1.10.0+)
`required`	`false`	If `false`, a missing secret is silently empty
`mode`	`0400`	Octal file mode
`uid`	`0`	Owning user
`gid`	`0`	Owning group

On the CLI side, --secret takes id=<name>,src=<file> for a file, id=<name>,env=<variable> to read from the environment, or just id=<name> when the variable already has the same name.

Two of those defaults cause most of the support traffic.

Permission denied on a secret that is definitely mounted

FROM node:22-slim
USER node
RUN --mount=type=secret,id=npmrc,target=/home/node/.npmrc npm ci

npm error code EACCES
npm error syscall open
npm error path /home/node/.npmrc
npm error errno -13

The mount worked. The file is there. ls -l inside the step would show it. But the documented defaults are mode=0400, uid=0, gid=0 — the file is readable by root and nobody else, and this stage runs as node.

The first diagnosis is almost always wrong: people go looking for a missing --secret on the command line, or add --chown to a COPY that has nothing to do with it, or — worst outcome — conclude secret mounts are broken and go back to an ARG.

Set the ownership on the mount to match the user the step runs as:

RUN --mount=type=secret,id=npmrc,target=/home/node/.npmrc,uid=1000,gid=1000 \
  npm ci

1000:1000 is node in that image. Confirm the numbers for your base rather than assuming; docker run --rm node:22-slim id node answers it.

`required=true`, always, in CI

required defaults to false. A build whose --secret flag was forgotten, misspelled, or lost in a YAML refactor does not fail — the mount is present and empty, and the command proceeds with no credentials.

For npm ci against a public registry that is invisible: the build succeeds, and you find out months later that a private package was resolving from a public typosquat. For curl it usually surfaces as a 401 buried in a step that swallows non-zero exits.

RUN --mount=type=secret,id=npmrc,required=true,target=/root/.npmrc \
  npm ci

Now a missing secret is a build failure with a clear message, which is what you wanted the pipeline to do in the first place.

Why an ARG-passed secret is in the image forever

Docker’s build-variables documentation states it plainly: “Build arguments and environment variables are inappropriate for passing secrets to your build, because they’re exposed in the final image.” The mechanism behind that sentence is what makes it non-negotiable.

Where the value actually goes, and why you cannot get it back

An OCI image is a config blob plus a set of layer blobs, referenced by a manifest. Everything is content-addressed: the config blob’s identity is the SHA-256 of its bytes, and the image digest is derived from the manifest that names it.

The config blob contains a history array. Each entry has a created_by field holding the build instruction that produced that step — with build arguments already substituted in. A --build-arg TOKEN=… therefore lands in created_by as literal text. docker history --no-trunc is just a pretty-printer for that array; anyone who can pull the image can read the same field straight out of the config blob without the Docker CLI at all.

ENV is worse again. Its values are in the config’s Env array, so they are in docker inspect, in the environment of every process in every container started from the image, and in anything that dumps /proc/self/environ.

With --provenance=mode=max, build arguments are also recorded in the provenance attestation attached alongside the image.

Now the part that decides your incident response. You cannot edit that config blob. Changing one byte changes its SHA-256, which changes the manifest, which changes the image digest — you have not scrubbed anything, you have created a different image. Meanwhile the original digest:

is still resolvable in the registry even after the tag is moved or deleted, until garbage collection runs and often after;
is in the local image store of every host that pulled it;
may be pinned by digest in a Compose file, a Kubernetes manifest, or a deployment record;
may be in a mode=max build cache exported to a registry.

There is exactly one remediation for a credential that reached an image config, and it is not a Docker command: rotate the credential. Everything else is theatre.

We deleted the tag, so it is fine

An engineer notices --build-arg NPM_TOKEN=… in a pipeline, removes it, rebuilds, and pushes :latest again. Ticket closed.

The old image is still in the registry, addressable by its digest. docker pull registry.example.com/myorg/app@sha256:... still works and docker history --no-trunc on the result still prints the token. Every CI job with read access to that registry can fetch it. So can anyone who kept the digest from a deployment log — and deployment logs are usually retained far longer, and read far more widely, than registry access is audited.

Even deleting the tag rarely removes the blob: registries do not garbage-collect on tag deletion, and most estates never run garbage collection at all.

The correct sequence is: rotate the credential first, then fix the pipeline, then clean up images at your leisure. If the token is revoked, the exposure is historical rather than live, and the cleanup stops being urgent. Do it in the other order and you spend the night deleting blobs while a valid token sits in a dozen caches.

Verifying secrets do not leak

Three checks, each of which can actually fail. Run them in CI, not by hand after an incident.

Read-only / Safescan history— Search the image config history for credential-shaped strings. Non-zero exit means something was found.

IMAGE=myorg/myapp:1.0.0
docker history --no-trunc --format '{{.CreatedBy}}' "$IMAGE" \
| grep -Ei 'token|secret|passwd|password|api[-_]?key|BEGIN [A-Z ]*PRIVATE KEY' \
&& echo 'FAIL: credential-shaped string in image history' && exit 1
echo 'history clean'

Read-only / Safeenv— Anything in Config.Env is visible to every process in every container from this image.

$ docker inspect --format '{{json .Config.Env}}' myorg/myapp:1.0.0

["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin","NODE_VERSION=22.14.0"]

Illustrative output

Then inspect the layers themselves:

docker save myorg/myapp:1.0.0 | tar -tvf -

Look for any file that might contain the secret. Common mistakes:

echo $SECRET > /some/file — the file ends up in the layer.
Logging the secret — the log ends up in the layer’s metadata.
Sending the secret in an HTTP request that gets logged by a sidecar — the request body may be cached in some logs.

The protection is “the secret file itself is not in any layer.” The protection is not “the secret cannot appear in a layer.”

The mount was clean and the tool wrote the credential anyway

RUN --mount=type=secret,id=npm_token \
  npm config set //registry.npmjs.org/:_authToken="$(cat /run/secrets/npm_token)" \
  && npm ci

The secret mount did its job perfectly. npm config set then wrote the token into /root/.npmrc, which is an ordinary file in an ordinary layer, and there it stays.

This is the general shape of the failure: the mount protects the mounted file, and nothing else. Any tool you hand the value to may persist it — npm config set, git remote add with an HTTPS token URL, pip config set, aws configure, a helper that writes ~/.docker/config.json.

Mount the credential where the tool already expects to find it instead of teaching the tool to write it down:

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true \
  npm ci

And if a tool insists on writing a file, delete it in the same RUN — a later RUN rm removes it from the merged view while leaving it in the earlier layer, fully readable to anyone who unpacks the tarball.

SSH mounts (`--mount=type=ssh`)

For builds that need SSH access (private Go modules, private git repositories):

RUN --mount=type=ssh \
  git clone git@github.com:myorg/private-repo.git

eval $(ssh-agent -s)
ssh-add ~/.ssh/id_ed25519
docker buildx build --ssh default .

The host’s SSH agent is forwarded to the build container for the duration of the step. After the step, the agent socket is gone.

The documented defaults: id is default, the socket appears at /run/buildkit/ssh_agent.${N}, mode is 0600, and required is false — so the same silent-failure warning applies. The N is the index of the mount within the instruction, which is why you rarely reference the path directly; BuildKit sets SSH_AUTH_SOCK for you.

Host key verification will fail, and that is correct

A fresh build container has no known_hosts, so the first git clone over SSH fails with Host key verification failed. The tempting fix — StrictHostKeyChecking=no — turns off the control that stops a poisoned DNS answer from feeding your build someone else’s repository.

Pin the host key instead, in the same RUN:

RUN --mount=type=ssh \
    mkdir -p -m 0700 ~/.ssh \
 && ssh-keyscan github.com >> ~/.ssh/known_hosts \
 && git clone git@github.com:myorg/private-repo.git

ssh-keyscan at build time still trusts the network on first use. For a build you actually care about, commit the expected host key into the repository and COPY it in, so the value is reviewed once rather than fetched fresh on every build.

Common pitfalls

Putting secrets in ENV or ARG. Visible in docker history --no-trunc and in the image metadata. Do not do this.
Putting secrets in a COPY from the build context. The secret file ends up in the layer. Do not do this.
Using a non-BuildKit builder. Legacy builders do not support secret mounts; secrets must be passed via ARG (visible) or via mount at runtime (does not help build).
Multi-stage with secrets. Secrets are scoped to the stage that uses them. They are not visible to subsequent stages by default. This is the correct behaviour; pass the secret explicitly to each stage.
Assuming rotation invalidates the build. It does not — see below.

What if the credential is rotated but the build still passes?

Docker’s cache-invalidation reference states that “The contents of build secrets are not part of the build cache”, while “Properties of secrets such as IDs and mount paths do participate in the cache checksum.”

That is the behaviour you want — a rotated token must not force a full rebuild of every image in the estate — but it produces a disconcerting sequence during an incident:

You revoke the leaked token.
CI runs. The RUN --mount=type=secret … npm ci step is CACHED, because nothing in its key changed. The build passes.
You conclude the revocation did not take effect, or that something is still using the old token.

Nothing is wrong. The step did not run, so it did not authenticate to anything. The first cold build — a new base image, a changed lockfile, a pruned builder — is when the revoked credential is actually exercised and the pipeline fails.

Verify a rotation properly rather than inferring it from a green build: docker buildx build --no-cache --target <the stage> on a throwaway tag, or exercise the credential directly against the service that issued it.

Build secrets (--mount=type=secret)