Docker Build Secrets: Use --secret Instead of ARG or ENV

Why ARG and ENV are the wrong place for build credentials#

This pattern looks convenient but leaks the credential into build metadata or the image configuration:

1
ARG NPM_TOKEN
2
RUN npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN && npm ci

Build arguments are not designed for secrets. Docker documents that values used in ARG can be visible in the image history, and modern BuildKit provenance can also record build arguments. An ENV value is even more obviously part of the image configuration and is inherited by later layers and containers.

The Dockerfile reference recommends secret mounts instead. A useful rule is:

If a value determines the output of a build, remember that a secret’s contents are not included in BuildKit’s cache checksum. A cached RUN can therefore be reused even after the secret changes; the cache invalidation guide explains how to add a non-secret cache-busting input when that behavior matters.

Mount a file secret with docker build --secret#

For a private npm registry, keep the local .npmrc outside the build context when possible and pass it as a secret source:

1
# syntax=docker/dockerfile:1
2
FROM node:22-alpine
3

4
WORKDIR /app
5
COPY package*.json ./
6

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

10
COPY . .
11
CMD ["npm", "start"]

Build the image with the matching secret ID:

1
docker build \
2
  --secret id=npmrc,src="$HOME/.npmrc" \
3
  --tag example-app:build-secrets .

The id connects the command-line source to the Dockerfile mount. The default mount location is /run/secrets/<id>, but target makes the path explicit for tools such as npm that already look for a configuration file. required=true changes a missing credential from a confusing package-install failure into an immediate mount error.

Do not add the secret file to COPY, and do not use a build argument to interpolate its contents into a RUN command. The secret is mounted only while that instruction runs. If the package manager creates a cache containing credentials, configure that cache separately and inspect what the tool writes.

Use an environment secret when the tool expects a variable#

BuildKit can read the source from the client environment instead of a file:

1
export GIT_AUTH_TOKEN='use-a-short-lived-token'
2
docker build \
3
  --secret id=GIT_AUTH_TOKEN,env=GIT_AUTH_TOKEN \
4
  --tag example-app:private-dependency .

Consume it in the one command that needs it:

1
RUN --mount=type=secret,id=GIT_AUTH_TOKEN,env=GIT_AUTH_TOKEN,required=true \
2
    ./scripts/download-private-dependency.sh

The command should read the variable and avoid echoing its environment. Prefer a short-lived, least-privilege token, and make sure CI masks the source variable in logs. The env option changes how the secret is exposed inside the instruction; it does not turn the value into a normal image-wide ENV variable.

Use an SSH mount for private Git dependencies#

An SSH agent is a different credential shape. Do not copy a private key into the image. Forward the agent only to the clone or install command:

1
# syntax=docker/dockerfile:1
2
FROM alpine:3.20
3

4
RUN apk add --no-cache git openssh-client
5
RUN mkdir -p -m 0700 /root/.ssh \
6
    && ssh-keyscan github.com >> /root/.ssh/known_hosts
7

8
RUN --mount=type=ssh \
9
    git clone [email protected]:example/private-library.git /opt/private-library

Build with the SSH agent that is already loaded on the client:

1
docker build --ssh default --tag example-app:private-git .

Use required=true on the SSH mount when the build must fail rather than silently falling back to an unauthenticated URL:

1
RUN --mount=type=ssh,id=default,required=true \
2
    git clone [email protected]:example/private-library.git /opt/private-library

The SSH mount forwards agent access for the instruction; it does not make the private key available as a normal file in the image.

Debug a secret that is “not available”#

When the build cannot see the credential, check the ID and source independently:

1. Confirm the --secret id=... ID exactly matches the Dockerfile id=....
2. Confirm the source file exists or the environment source is set in the process that invokes docker build.
3. Add required=true while diagnosing so a missing mount fails at the boundary.
4. Check that the command reads the mounted path or environment name you selected.
5. Confirm the build is using BuildKit and the Dockerfile syntax version supports the mount.
6. Re-run with a harmless existence check, never with a command that prints the secret.

For a file mount, this test verifies only that the file is present:

1
RUN --mount=type=secret,id=license,target=/run/secrets/license,required=true \
2
    test -s /run/secrets/license

Do not replace the check with cat /run/secrets/license. Build logs are another output channel, and a secret that is absent from the final image can still be exposed by the build log.

Verify the image and build configuration#

After a successful build, inspect the history and the generated image without printing the credential:

1
docker history --no-trunc example-app:build-secrets
2
docker image inspect example-app:build-secrets

Look for accidental ARG, ENV, or shell commands containing the credential. These checks cannot prove that an arbitrary build script did not persist a secret, so also review the command that consumed the mount and any files it generated. If a real credential was exposed in history, logs, a layer, or a deployed image, rotate it and rebuild; deleting the Dockerfile line does not revoke a leaked token.

If the failure is instead COPY failed: file not found, debug the build context and .dockerignore boundary with Docker COPY failed: file not found. Secret mounts solve credential handling, not files that were never sent to the builder.

The practical rule is simple: use ARG for public build choices, ENV for intentional runtime configuration, and secret or SSH mounts for credentials that exist only while one build instruction runs.

FAQ#