During a Docker image build you need a private credential, for example a package registry token or an SSH key for a private Git dependency. How do you supply it so it never ends up in the published image?

## Why the naive approaches leak An image is an ordered set of immutable layers plus a config blob. Three properties follow. First, **layers are additive and permanent**. COPY id_rsa . creates a layer containing that file. A later RUN rm id_rsa creates another layer with a whiteout marker so the file is invisible in the merged view, but the earlier layer still ships with the image. Anyone who pulls it can docker save the image and read the key out of the tarball. Second, **build args and ENV are recorded in metadata**. Values passed with --build-arg appear in the image configuration and are visible with docker history. ENV values are part of the image config by design and are also injected into the environment of every process in every container from that image, so they leak both at rest and at runtime. Third, **caches and logs are exposed too**. Exported build caches, CI logs and build summaries can all carry a credential passed by a mechanism that treats it as ordinary build data. ## The secret mount BuildKit adds RUN --mount=type=secret. The build is invoked with docker build --secret id=<name>,src=<path> (or env=<VAR> to take it from the environment of the CLI, or with no src to default to an env var of the same name). During that single RUN instruction, the value is mounted as a file, by default at /run/secrets/<id>, on a tmpfs. When the instruction finishes, the mount is gone. Nothing about it is committed to a layer, recorded in history, or written into the exported cache. You can control target, mode, uid and gid, and mark it required so the build fails loudly rather than silently proceeding without the credential. The key discipline is that the secret must be consumed inside the same RUN that mounts it. Reading it into an ENV, or writing it to a file under the working directory, defeats the whole mechanism, because now it is in the layer. ``` # syntax=docker/dockerfile:1 FROM node:22 RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true npm ci ``` Mounting straight to the config path the tool expects is often cleaner than catting the file into a variable, because the value never appears in a shell command line where it might be echoed by set -x. ## The ssh mount Private Git dependencies are the other common case. RUN --mount=type=ssh forwards the host SSH agent socket into the build, invoked as docker build --ssh default. The agent performs the signing; the private key never enters the build environment at all, so there is nothing to leak even in principle. You still need the host key in known_hosts, typically via ssh-keyscan in the same RUN, and the mount must be present on every RUN that reaches out to the private remote. ``` RUN --mount=type=ssh mkdir -p -m 0700 ~/.ssh \ && ssh-keyscan github.com >> ~/.ssh/known_hosts \ && go mod download ``` ## Verification and incident handling To prove a build does not leak, inspect what shipped rather than trusting the Dockerfile: docker history --no-trunc shows build args and instructions; docker save piped into a tar listing lets you grep layer contents; dive or a scanner with secret detection automates it. Many organisations run a secret-scanning gate over built images in CI for exactly this. If a credential did reach a pushed image, treat it as disclosed. Registry layers may be cached by consumers, mirrored, or already pulled. Deleting the tag does not recall the bytes. Rotate the credential, then fix the Dockerfile. ## Alternatives worth naming Multi-stage builds are sometimes offered as the answer: fetch dependencies in a build stage using a credential, then copy only the artefacts into the final stage. That does keep the credential out of the final image, and it is a legitimate pattern, but the intermediate stage still contains the secret in its layers, which matters if that stage is cached, exported, or pushed as a cache target. Secret mounts are the cleaner answer and compose fine with multi-stage builds. On platforms with a build service (CI runners, cloud builders), the strongest option is often not to hand the build a long-lived credential at all: use short-lived, workload-identity-issued tokens so a leak has a small blast radius. That is the principal-level framing to add on top of the mechanism.