GitHub Actions docker build "--secret id not provided"

By Kaveh Alemi·Latchkey

A Dockerfile that mounts a build secret with --mount=type=secret,id=X requires that id to be supplied via the build secrets input. If it is missing, BuildKit fails because the secret is undefined. This is a config error.

What this error means

The docker build step fails because a RUN --mount=type=secret references an id that the build was never given.

ERROR: failed to solve: secret "npm_token" not found
build definition requires secret id "npm_token" which was not provided

Common causes

Secret id not passed to the build action

The Dockerfile mounts a secret by id, but build-push-action secrets input does not define it.

id name mismatch

The id in the Dockerfile does not match the id provided in the build secrets.

How to fix it

Pass the secret with a matching id

1. Provide the secret via the secrets input with id=<name> matching the Dockerfile mount.
2. Source the value from a GitHub Actions secret.
3. Keep the id identical on both sides.

- uses: docker/build-push-action@v6
  with:
    context: .
    secrets: |
      npm_token=${{ secrets.NPM_TOKEN }}

How to prevent it

• Keep secret ids identical between the Dockerfile mount and the build secrets input.
• Pass every mounted secret id the Dockerfile references.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions