How to Set Up Docker Buildx

name: 'Usage of setup-buildx-action GitHub Action'
on:
    push:
        branches:
            - main
jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v4
        -
        # Add support for more platforms with QEMU (optional)
        # https://github.com/docker/setup-qemu-action
        name: Set up QEMU
        uses: docker/setup-qemu-action@v3

        - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

Setup BuildX Action

GitHub Action to set up Docker Buildx

What is Buildx?​

This GitHub Action creates and starts a Docker builder, which can be further used in your workflow for those using Buildx or the build-push action. By default, docker-container driver is used to enable building of multi-platform images and export cache using BuildKit container.

How to Pin Docker Buildx Versions​

By default, the action will use the latest versions of Buildx and BuildKit available on the GitHub Runner. However, you can pin specific versions of Buildx and BuildKit by using the version and driver-opts inputs.

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    version: v0.10.0
    driver-opts: image=moby/buildkit:v0.11.0 # optional

How to Display BuildKit Container Logs​

To display BuildKit container logs when using the docker-container driver, you must either enable step debug logging or set the --debug buildkitd flag in the Docker Setup Buildx action.

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    buildkitd-flags: --debug

- name: Build
  uses: docker/build-push-action@v5
  with:
    context: .

How to Provide BuildKit Daemon Configuration​

You can provide a BuildKit configuration to your builder if you're using the docker-container driver (default) with the config or config-inline inputs.

Registry Mirror​

You can configure a registry mirror using an inline block directly in your workflow with the config-inline input:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          config-inline: |
            [registry."docker.io"]
              mirrors = ["mirror.gcr.io"]

Parallelism​

You can limit the parallelism of the BuildKit solver, which is particularly useful for low-powered machines.

You can use the config-inline input like the previous example, or you can use a dedicated BuildKit config file from your repository with the config input.

[worker.oci]
  max-parallelism = 4

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    config: .github/buildkitd.toml

How to Append Additional Nodes to the Builder​

Buildx supports running builds on multiple machines, which is useful for building multi-platform images on native nodes for more complicated cases. Building on native nodes generally has better performance and allows you to distribute the build across multiple machines.

You can append nodes to the builder using the append option. It takes input in the form of a YAML string document to overcome limitations in GitHub Actions where only strings can be used in input fields.

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    driver: remote
    endpoint: tcp://oneprovider:1234
    append: |
      - endpoint: tcp://graviton2:1234
        platforms: linux/arm64
      - endpoint: tcp://linuxone:1234
        platforms: linux/s390x            
  env:
    BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.ONEPROVIDER_CA }}
    BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.ONEPROVIDER_CERT }}
    BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.ONEPROVIDER_KEY }}
    BUILDER_NODE_1_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
    BUILDER_NODE_1_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
    BUILDER_NODE_1_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
    BUILDER_NODE_2_AUTH_TLS_CACERT: ${{ secrets.LINUXONE_CA }}
    BUILDER_NODE_2_AUTH_TLS_CERT: ${{ secrets.LINUXONE_CERT }}
    BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }}