Agent Wranglers

ENG-69Required

Pass build secrets as mounts instead of layers

Give the build a token or key only through a secret mount. Never through ARG, ENV, or a copied file.

By Agent Wranglers. Updated .

How to do it

Build arguments and environment variables stay readable in the image and its history. With BuildKit, write RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN npm ci and build with --secret id=npm_token. The secret exists only while that step runs. Runtime secrets come from the secrets store.

Examples

Dockerfile example

# Bad: the token stays in the image history
ARG NPM_TOKEN
RUN NPM_TOKEN=$NPM_TOKEN npm ci

# Good: mounted for one step only
RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN npm ci

Shell example

docker build --secret id=npm_token,env=NPM_TOKEN -t shop .

How to check

docker history --no-trunc shop and a secret scanner run over the saved image find no token.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/build-secrets">Agent Wranglers engineering playbook</a>. In code you write, add a comment next to it with the same link.