doc bug: secrets, secret-envs and secret-files documentation is horrible

[breathe]

Contributing guidelines

• [x] I've read the contributing guidelines and wholeheartedly agree

I've found a bug, and:

• [ ] The documentation does not mention anything about my problem
• [ ] There are no open or closed issues that are related to my problem

Description

The documentation written:

List of [secret files](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret) to expose to the build (e.g., key=filename, MY_SECRET=./secret.txt)

I think key=filename in each of these examples is supposed to be explaining that the only allowed syntax is key=value one per line. However as written these meanings are ridiculously unclear. The mapping from these settings to the 'normal' syntax for secrets via docker cli is not clear at all -- which makes the docs linked similarly unclear.

These examples should be rewritten to show the cli options that even a single example use of this feature would correspond to semantically ...

List of [secret files](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret) to expose to the build.  Example: `MY_SECRET=./secret.txt` translates to this cli `--secret id=MY_SECRET,type=file,src=./secret.txt`

Expected behaviour

The documentation would make it easy to interpret what values should be supplied

Actual behaviour

The documentation links to explanation that uses spelling with insufficient information to infer how to interpret that documentation from the source context.

Repository URL

No response

Workflow run URL

No response

YAML workflow

`secret-files:`

Workflow logs

No response

BuildKit logs

Additional info

No response

[crazy-max]

We have dedicated docs for GitHub Actions and secrets usage at https://docs.docker.com/build/ci/github-actions/secrets/

Manuals section also covers CLI usage: https://docs.docker.com/build/building/secrets/

[synack-badamson]

I'm not seeing secret-envs documented there.

[crazy-max]

I'm not seeing secret-envs documented there.

Yes we could have a note for this input in https://docs.docker.com/build/ci/github-actions/secrets/

[daveneeley]

We have dedicated docs for GitHub Actions and secrets usage at https://docs.docker.com/build/ci/github-actions/secrets/

Manuals section also covers CLI usage: https://docs.docker.com/build/building/secrets/

What information in the readme of this repository explains that there are better docs somewhere else? Could that be added?

[crazy-max]

What information in the readme of this repository explains that there are better docs somewhere else? Could that be added?

• https://github.com/docker/build-push-action/blob/84ad562665bb303b549fec655d1b64f9945f3f91/README.md?plain=1#L159
• https://github.com/docker/build-push-action/blob/84ad562665bb303b549fec655d1b64f9945f3f91/README.md?plain=1#L251-L253

[GorlikItsMe]

whats the difference betwen secrets and secret-envs ?

---

Edit: Note for future me:

How to make env works github-actions

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          ...
          secrets: |
            SENTRY_AUTH_TOKEN=${{ secrets.SENTRY_AUTH_TOKEN }}

dockerfile

RUN --mount=type=secret,id=SENTRY_AUTH_TOKEN,env=SENTRY_AUTH_TOKEN \
  bun run build

;-)

[ankurk91]

This is how i was able to use the secrets in github actions

      - name: Build and push to ECR
        uses: docker/build-push-action@v6
        with:
          platforms: linux/amd64
          context: .
          push: true
          secrets: |
            AWS_ACCESS_KEY_ID=${{ secrets.AWS_ACCESS_KEY_ID }}
            AWS_SECRET_ACCESS_KEY=${{ secrets.AWS_SECRET_ACCESS_KEY }}
            AWS_REGION=${{ vars.AWS_REGION }}

# Builder stage code not pasted here

FROM public.ecr.aws/aws-cli/aws-cli:latest AS uploader

WORKDIR /files

ARG NEXT_ASSET_BUCKET_NAME
ENV NEXT_ASSET_BUCKET_NAME=$NEXT_ASSET_BUCKET_NAME

COPY --from=builder /build/.next/static ./static

RUN --mount=type=secret,id=AWS_ACCESS_KEY_ID \
    --mount=type=secret,id=AWS_SECRET_ACCESS_KEY \
    --mount=type=secret,id=AWS_SESSION_TOKEN \
    --mount=type=secret,id=AWS_REGION \
    bash -c '\
    aws configure set aws_access_key_id "$(cat /run/secrets/AWS_ACCESS_KEY_ID)" && \
    aws configure set aws_secret_access_key "$(cat /run/secrets/AWS_SECRET_ACCESS_KEY)" && \
    aws configure set region "$(cat /run/secrets/AWS_REGION)" && \
    aws sts get-caller-identity && \
    aws s3 sync ./static "s3://'"$NEXT_ASSET_BUCKET_NAME"'/_next/static" \
        --delete \
        --no-progress \
        --cache-control "max-age=604800" 
    '

[y-nk]

@GorlikItsMe i couldn't make this way work with pnpm :(