How to Configure a Buildx Builder Instance in CI

setup-buildx-action provisions a docker-container BuildKit instance, which unlocks cache exports and multi-platform builds.

The default Docker driver cannot export cache or build multiple platforms. docker/setup-buildx-action creates a docker-container builder that can, and accepts driver-opts and a buildkitd-config for tuning.

Steps

• Add docker/setup-buildx-action to create a docker-container builder.
• Pass driver-opts (e.g. an image or network) as needed.
• Supply buildkitd-config-inline for registry mirrors or limits.

Workflow

- uses: docker/setup-buildx-action@v3
  with:
    driver: docker-container
    driver-opts: |
      network=host
    buildkitd-config-inline: |
      [worker.oci]
        max-parallelism = 4

Gotchas

• Cache export (cache-to) and multi-platform builds require the docker-container driver, not the default docker driver.
• Images built with the container driver are not in the local daemon unless you add load: true.

Related guides