5.2.3.1 ARG Secret Avoidance
A focused guide to ARG Secret Avoidance, connecting core concepts with practical Docker and container operations.
ARG secret avoidance is the principle that build arguments (ARG) should never be used to pass genuinely sensitive values into a build, because their values can become visible in image history and in build logs, unlike BuildKit's dedicated secret mounts, which are specifically designed to avoid this exposure.
How an ARG-Based Secret Can Leak
A value passed via --build-arg can end up visible through docker history, depending on how it is used within the Dockerfile, and is also often visible directly in CI build logs where the build command itself is recorded.
ARG API_KEY
RUN curl -H "Authorization: Bearer $API_KEY" https://api.example.com/setup
docker build --build-arg API_KEY=secret123 -t myapp .
docker history myapp
Depending on exactly how the value is used, this history command can reveal the supplied secret value directly.
The Correct Alternative: Secret Mounts
A genuinely sensitive value should instead be supplied through a secret mount, which is specifically designed so the value never appears in image history or layer content at all.
RUN --mount=type=secret,id=api_key \
curl -H "Authorization: Bearer $(cat /run/secrets/api_key)" https://api.example.com/setup
docker build --secret id=api_key,src=./api_key.txt -t myapp .
Recognizing When a Value Is Sensitive Enough to Warrant This Care
Not every build argument needs this level of protection — a version number or a feature flag poses no risk if exposed — but any value that grants access to something (an API key, a token, a password) should always be treated as requiring secret mount handling, never plain ARG.
ARG VERSION=1.0
RUN --mount=type=secret,id=db_password ...
The first is fine as an ordinary build argument; the second is exactly the kind of value that should never be passed as one.
Why ARG Secret Avoidance Matters
Consistently recognizing the distinction between ordinary build configuration values and genuinely sensitive credentials, and routing the latter exclusively through secret mounts rather than ARG, prevents a serious and entirely avoidable category of accidental secret exposure in build artifacts and logs.