basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    A build token goes through --secret, not ARG

    ARG and ENV are no good for secrets: the value stays in the image, and everyone who pulled the image can see it. Pass a token needed only during the build — for a private npm registry or a private repository — with docker build --secret: it shows up in one RUN and doesn’t stay in the layers.

    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 build has no --secret, or its id doesn’t match the id in RUN --mount. Without required=true a missing secret is silently skipped.
    Fix
    Use the same id in both places and required=true in RUN --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_'
    # 0

    Not verified yet

    1. BuildKit in Docker 29 writes the ARG value into the image history at the RUN line that uses the ARG ↑