About

GitHub Action to use Docker Buildx Bake as a high-level build command.

---

• Usage
  • Git context
  • Path context
• Summaries
• Customizing
  • inputs
  • outputs
  • environment variables
• Subactions
  • matrix
• Notes
  • Source semantics
• Contributing

Usage

Git context

Since v6 this action uses the Git context to build from a remote bake definition by default like the build-push-action does. This means that you don't need to use the actions/checkout action to check out the repository as BuildKit will do this directly.

The git reference will be based on the event that triggered your workflow and will result in the following context: https://github.com/<owner>/<repo>.git#<ref>.

name: ci

on:
  push:

jobs:
  bake:
    runs-on: ubuntu-latest
    steps:
      -
        name: Login to DockerHub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      -
        name: Build and push
        uses: docker/bake-action@v7
        with:
          push: true
          set: |
            *.tags=user/app:latest

Be careful because any file mutation in the steps that precede the build step will be ignored, including processing of the .dockerignore file since the context is based on the Git reference. However, you can use the Path context using the source input alongside the actions/checkout action to remove this restriction.

Default Git context can also be provided using the Handlebars template expression {{defaultContext}}. Here we can use it to provide a subdirectory to the default Git context:

      -
        name: Build and push
        uses: docker/bake-action@v7
        with:
          source: "{{defaultContext}}:mysubdir"
          push: true
          set: |
            *.tags=user/app:latest

Building from the current repository automatically uses the GITHUB_TOKEN secret that GitHub automatically creates for workflows, so you don't need to pass that manually. If you want to authenticate against another private repository for remote definitions, you can set the BUILDX_BAKE_GIT_AUTH_TOKEN environment variable.

Note

Supported since Buildx 0.14.0

      -
        name: Build and push
        uses: docker/bake-action@v7
        with:
          push: true
          set: |
            *.tags=user/app:latest
        env:
          BUILDX_BAKE_GIT_AUTH_TOKEN: ${{ secrets.MYTOKEN }}

Path context

name: ci

on:
  push:

jobs:
  bake:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v6
      -
        name: Login to DockerHub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      -
        name: Build and push
        uses: docker/bake-action@v7
        with:
          source: .
          push: true
          set: |
            *.tags=user/app:latest

If you point source to a subdirectory, relative paths are resolved from that subdirectory:

      -
        name: Build and push
        uses: docker/bake-action@v7
        with:
          source: ./subdir
          files: ./docker-bake.hcl

For example, if ./subdir/docker-bake.hcl contains:

target "default" {
  output = ["type=local,dest=./artifacts"]
}

The output will be written to ./subdir/artifacts in the workspace.

Note

More info about source semantics in the Source semantics section.

Summaries

This action generates a job summary that provides a detailed overview of the build execution. The summary shows an overview of all the steps executed during the build, including the build inputs, bake definition, and eventual errors.

The summary also includes a link for downloading a build record archive with additional details about the build execution for all the bake targets, including build stats, logs, outputs, and more. The build record can be imported to Docker Desktop for inspecting the build in greater detail.

Warning

If you're using the actions/download-artifact action in your workflow, you need to ignore the build record artifacts if name and pattern inputs are not specified (defaults to download all artifacts of the workflow), otherwise the action will fail:

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

More info: https://github.com/actions/toolkit/pull/1874

Summaries are enabled by default, but can be disabled with the DOCKER_BUILD_SUMMARY environment variable.

For more information about summaries, refer to the documentation.

Customizing

inputs

The following inputs can be used as step.with keys

List type is a newline-delimited string

set: target.args.mybuildarg=value

set: |
  target.args.mybuildarg=value
  foo*.args.mybuildarg=value

CSV type is a comma-delimited string

targets: default,release

Name	Type	Description
builder	String	Builder instance (see setup-buildx action)
allow	List/CSV	Allow build to access specified resources (e.g., network.host)
call	String	Set method for evaluating build (e.g., check)
files	List/CSV	List of bake definition files
no-cache	Bool	Do not use cache when building the image (default false)
pull	Bool	Always attempt to pull a newer version of the image (default false)
load	Bool	Load is a shorthand for --set=*.output=type=docker (default false)
provenance	Bool/String	Provenance is a shorthand for --set=*.attest=type=provenance
push	Bool	Push is a shorthand for --set=*.output=type=registry (default false)
sbom	Bool/String	SBOM is a shorthand for --set=*.attest=type=sbom
set	List	List of targets values to override (e.g., targetpattern.key=value)
source	String	Build source to use. Supports local path and remote bake definition. With a local path, Bake runs from that directory, so all relative paths are resolved from it. See Source semantics.
targets	List/CSV	List of bake targets (default target used if empty)
github-token	String	API token used to authenticate to a Git repository for remote definitions (default ${{ github.token }})

outputs

The following outputs are available

Name	Type	Description
metadata	JSON	Build result metadata

environment variables

Name	Type	Default	Description
DOCKER_BUILD_CHECKS_ANNOTATIONS	Bool	true	If false, GitHub annotations are not generated for build checks
DOCKER_BUILD_SUMMARY	Bool	true	If false, build summary generation is disabled
DOCKER_BUILD_RECORD_UPLOAD	Bool	true	If false, build record upload as GitHub artifact is disabled
DOCKER_BUILD_RECORD_RETENTION_DAYS	Number		Duration after which build record artifact will expire in days. Defaults to repository/org retention settings if unset or 0

Subactions

• matrix

Notes

Source semantics

source accepts either a Git/remote bake definition (for example {{defaultContext}} or {{defaultContext}}:subdir) or a local path (for example . or ./subdir). When source is a local path, the action runs Bake from that directory (equivalent to cd <path> && docker buildx bake).

This local path mode affects all relative paths resolved by Bake, not only target context fields. This includes paths used by local outputs, cache import/export, and cwd:// references.

source	Behavior
Git/remote ({{defaultContext}}, https://...git#ref, ...:subdir)	Uses remote bake definition behavior.
Local path (., ./subdir)	Changes Bake working directory to that path before invoking Bake.

Contributing

Want to contribute? Awesome! You can find information about contributing to this project in the CONTRIBUTING.md