19 Nov, 2026Aishwarya Palta
Docker Build Secrets: Use Secret Mounts
Pass Docker build secrets with BuildKit secret mounts. Fetch private npm packages without copying credentials into layers, and check how your build uses them.
Docker Build Secrets: Use Secret Mounts
Docker build secrets let a build authenticate to private services without placing credentials in ordinary image instructions. Use BuildKit secret mounts for access tokens and configuration files required during a specific build step
Our developer view: give the dependency installation step temporary access to its credentials, and inspect what that step writes. A secret mount controls delivery; the invoked command can still disclose the value.
Why avoid ARG and COPY for credentials?
Build arguments can expose values through image metadata or history. Copying credentials into a layer and deleting them in a later layer leaves the earlier layer available. Docker recommends [secret or SSH mounts](https://docs.docker.com/build/building/secrets/) instead.
For a Node.js application using private npm packages, keep the authenticated `.npmrc` outside the build context. This example assumes committed dependency manifests:
```dockerfile
# syntax=docker/dockerfile:1
FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true npm ci
COPY . .
RUN npm run build
```Pass your local npm configuration when building:
docker build --secret id=npmrc,src="$HOME/.npmrc" -t app:test .
Exclude `.npmrc`, local `node_modules` and secret-bearing files from the context using `.dockerignore`. If an installation script needs application files, copy only those required inputs before installation.
What changes in GitHub Actions?
Supply the credential through the build action’s secret input rather than embedding it in the Dockerfile. Docker’s GitHub Actions secret guide documents environment, file and multiline sources.
Keep credentials scoped to the packages needed. Review dependency lifecycle scripts, since they execute while the mount is available. Avoid shell tracing, diagnostic printing or copying the mounted file elsewhere.
What should you verify before merging?
Run a build with the expected secret and confirm dependency installation succeeds. Check logs and generated artifacts for disclosure; test missing-credential behavior with a fresh build because cached installation can bypass that step.
Review Docker workflow setup, runner isolation and secret scanning as complementary controls.
Takeaway: secret mounts reduce accidental persistence, but safe handling also depends on the commands, dependencies and outputs inside the build.