docker/build-push-action

While building from the current repository uses the automatic GitHub Token, you must provide a secret named GIT_AUTH_TOKEN if you need to authenticate against a different private repository during the build process.

      -
        name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          secrets: |
            GIT_AUTH_TOKEN=${{ secrets.MYTOKEN }}

The action automatically generates a GitHub job summary providing an overview of build execution, including inputs and errors. It also produces a build record (with .dockerbuild extension) containing build stats and logs that can be imported into Docker Desktop.

Note for actions/download-artifact users: If you use actions/download-artifact@v4 without specifying a name or pattern, the workflow may fail because it tries to download the build record artifacts. To avoid this, use a negative pattern to ignore them:

- uses: actions/download-artifact@v4
  with:
    pattern: "!*.dockerbuild"

By default, docker/build-push-action uses the Git context, meaning you do not need to use actions/checkout to check out your repository; BuildKit handles the checkout directly from the Git reference.

Important: Because the context is based on the Git reference, any file mutations (changes) made in previous steps—including modifications to the .dockerignore file—will be ignored.

To use a specific subdirectory within the default Git context, use the Handlebars template expression {{defaultContext}} with a colon separator.

      -
        name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: "{{defaultContext}}:mysubdir"
          push: true
          tags: user/app:latest

The action supports adding attestations to your builds.

• Provenance: Use the provenance input or include type=provenance in the attests list.
• SBOM: Use the sbom input or include type=sbom in the attests list.
• Default Behavior: If attests is not provided and BuildKit version is compatible (>= 0.11.0), the action sets default provenance based on repository visibility:
  • Private Repositories: mode=min,inline-only=true
  • Public Repositories: mode=max

Note: Attestations require buildx >= 0.10.0.

If you encounter errors during the push process (such as invalid content digest, no response, 400 Bad Request, or 401 Unauthorized), these issues are typically related to Buildx, BuildKit, containerd, or the destination registry rather than the build-push-action itself.

To diagnose these issues, you must enable debugging in the setup-buildx action step and provide the BuildKit container logs when reporting the issue.

You can control whether build warnings are converted into GitHub annotations using the DOCKER_BUILD_CHECKS_ANNOTATIONS environment variable. By default, this is enabled.

Set DOCKER_BUILD_CHECKS_ANNOTATIONS to false to disable this feature.

The build summary feature (which provides a detailed report in the GitHub Action summary) can be controlled via environment variables:

• DOCKER_BUILD_SUMMARY: Set to false to disable the build summary.
• DOCKER_BUILD_RECORD_UPLOAD: Set to true to enable uploading the build record as a GitHub artifact.
• DOCKER_BUILD_RECORD_RETENTION_DAYS: Specifies the number of days to retain the uploaded build record artifact.

You can control the behavior of the action using the following environment variables: