Pass Docker build credentials through dedicated secret mounts

Build arguments and environment variables can leave credentials in the resulting image.

Source facts

Docker documents build arguments and environment variables as inappropriate ways to pass build secrets because they persist in the image. Secret mounts or SSH mounts are the supported alternatives. The workflow has two parts: pass the secret to the build command, then consume it in the Dockerfile. A secret mount is temporarily available for the relevant build instruction.

Source: Docker documentation — Build secrets.

Applicability

Review credentials consumed during image build through Docker’s secret or SSH mount workflow.

DSE recommendation

DSE recommends inventorying private package, repository, and signing access used by the build. Replace embedded credentials with the supported mount mechanism and keep secret values out of Dockerfile arguments, logs, and diagnostic traces. Review the build instruction to ensure it does not write the credential into an artifact that is later copied into the final image. Assign rotation and access ownership to the build identity. Separate the credential’s lifecycle from the generated image’s deployment lifecycle.

Verification

In an isolated build using a disposable credential, inspect the final image’s intended files and relevant metadata without printing secret values. Confirm the build succeeds only through its approved secret input and that the credential is unavailable to ordinary runtime processes. Revoke the disposable credential after verification. Retain the reviewed instruction and a sanitized inventory of the final artifact. Have the build owner identify any intermediate output that could copy sensitive material, and verify its disposition before accepting the credential-handling change.

Official reference

Docker documentation — Build secrets. Reviewed October 20, 2026.