How it leaks
FROM node:24.22.1-alpine
WORKDIR /app
COPY package.json package-lock.json ./
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc \
&& npm ci --omit=dev \
&& rm .npmrc
COPY . .
CMD ["node", "server.js"]
rm .npmrc in the same RUN means the file isn’t in the layer. But Docker writes the ARG value into the
image history together with the RUN line that uses it: docker history --no-trunc shows NPM_TOKEN=npm_…
to anyone who pulled the image1.
With ENV NPM_TOKEN=… it’s even simpler: docker inspect --format '{{.Config.Env}}' prints it.
A multi-stage build (Multi-stage build) covers this only partly: the build stage’s history doesn’t get
into the final image. But build that stage on its own, --target build, and the token is in the image again.
How to pass it
FROM node:24.22.1-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true npm ci --omit=dev
COPY . .
CMD ["node", "server.js"]
docker build --secret id=npmrc,src=$HOME/.npmrc -t app:dev .
For the duration of one RUN, the ~/.npmrc file from the build machine appears in the container at
/root/.npmrc — where npm looks for the root user’s settings. After RUN the file is neither in the layer
nor in the image history.
In GitHub Actions it’s the same — the secrets input of docker/build-push-action, with the contents of
.npmrc stored in the repository secrets:
- uses: docker/build-push-action@v7
with:
secrets: npmrc=${{ secrets.NPMRC }}
Keep ARG for what’s public anyway: the version, the API address, the site ID in a visitor counter — it’s in
the code of every page regardless.
If it doesn’t work
npm ci in the build fails on a private package: 404 Not Found or 401 Unauthorized
- Cause
- The secret didn’t reach
RUN:docker buildhas no--secret, or itsiddoesn’t match theidinRUN --mount. Withoutrequired=truea missing secret is silently skipped. - Fix
- Use the same
idin both places andrequired=trueinRUN --mount: then the build fails right away with a clear error.
The token was already built in through ARG, and the image is in the registry
- Cause
- The value is written into the image history.
- Fix
- Rebuild with
--secret, delete the old tags from the registry, revoke the token and issue a new one (A secret in a commit — same order).
How to check
There are no npm tokens (they start with npm_) in the image history:
docker history --no-trunc app:dev | grep -c 'npm_'
# 0Not verified yet
- BuildKit in Docker 29 writes the ARG value into the image history at the RUN line that uses the ARG ↑