---
title: "Pass build secrets as mounts instead of · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/build-secrets
id: ENG-69
level: Required
applies: servers
risk: takeover
updated: 2026-10-27
build: a2a6bdfed830
tokens: 713
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Pass build secrets as mounts instead of layers

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ENG-69
- Level: Required
- Chapter: [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md)
- Rule: Give the build a token or key only through a secret mount. Never through `ARG`, `ENV`, or a copied file.
- Check: `docker history --no-trunc shop` and a secret scanner run over the saved image find no token.
- Risk: An account or system taken over
- Applies when: The project runs its own servers, virtual machines or containers.
- How: 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](https://agentwranglers.se/playbook/engineering/running-in-production/secrets-store.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Dockerfile example

```dockerfile
# 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

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

## Sources

- [Docker build secrets](https://docs.docker.com/build/building/secrets/)
- [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)

## Related rules

- ENG-26 [Keep secrets in a secrets store](https://agentwranglers.se/playbook/engineering/running-in-production/secrets-store.md) in Engineering

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Run outside code only on runners that are wiped after each job](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/ephemeral-ci-runners.md)
- Next: [Scan every image before it ships](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/image-scanning.md)
- [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md)