setup-buildx-action/README.md

About

GitHub Action to set up Docker Buildx.

This action will create and boot a builder that can be used in the following steps of your workflow if you're using buildx. By default, the docker-container builder driver will be used to be able to build multi-platform images and export cache thanks to the BuildKit container.

---

• Usage
  • Quick start
  • With QEMU
  • Install by default
  • BuildKit daemon configuration
    • Registry mirror
    • Max parallelism
  • Standalone mode
• Customizing
  • inputs
  • outputs
  • environment variables
• Notes
  • BuildKit container logs
• Keep up-to-date with GitHub Dependabot

Usage

Quick start

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v3
      -
        name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@v2
      -
        name: Inspect builder
        run: |
          echo "Name:      ${{ steps.buildx.outputs.name }}"
          echo "Endpoint:  ${{ steps.buildx.outputs.endpoint }}"
          echo "Status:    ${{ steps.buildx.outputs.status }}"
          echo "Flags:     ${{ steps.buildx.outputs.flags }}"
          echo "Platforms: ${{ steps.buildx.outputs.platforms }}"          

With QEMU

If you want support for more platforms you can use our setup-qemu action:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v3
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v2
      -
        name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@v2
      -
        name: Available platforms
        run: echo ${{ steps.buildx.outputs.platforms }}

Install by default

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v3
      -
        uses: docker/setup-buildx-action@v2
        id: buildx
        with:
          install: true
      -
        name: Build
        run: |
          docker build . # will run buildx          

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: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
        with:
          config-inline: |
            [registry."docker.io"]
              mirrors = ["mirror.gcr.io"]            

Max 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 repo if you want with the config input:

# .github/buildkitd.toml
[worker.oci]
  max-parallelism = 4

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
        with:
          config: .github/buildkitd.toml

Standalone mode

If you don't have the Docker CLI installed on the GitHub Runner, buildx binary is invoked directly, instead of calling it as a docker plugin. This can be useful if you want to use the kubernetes driver in your self-hosted runner:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2
        with:
          driver: kubernetes
      -
        name: Build
        run: |
          buildx build .          

Customizing

inputs

Following inputs can be used as step.with keys

Name	Type	Description
version	String	buildx version. (eg. v0.3.0, latest, https://github.com/docker/buildx.git#master)
driver	String	Sets the builder driver to be used (default docker-container)
driver-opts	CSV	List of additional driver-specific options (eg. image=moby/buildkit:master)
buildkitd-flags	String	Flags for buildkitd daemon (since buildx v0.3.0)
install	Bool	Sets up docker build command as an alias to docker buildx (default false)
use	Bool	Switch to this builder instance (default true)
endpoint	String	Optional address for docker socket or context from docker context ls
config¹	String	BuildKit config file
config-inline¹	String	Same as config but inline

• ¹ config and config-inline are mutually exclusive

CSV type must be a newline-delimited string

driver-opts: image=moby/buildkit:master

driver-opts: |
  image=moby/buildkit:master
  network=host  

outputs

Following outputs are available

Name	Type	Description
name	String	Builder name
driver	String	Builder driver
endpoint	String	Builder node endpoint
status	String	Builder node status
flags	String	Builder node flags (if applicable)
platforms	String	Builder node platforms available (comma separated)

environment variables

The following official docker environment variables are supported:

Name	Type	Default	Description
DOCKER_CONFIG	String	~/.docker	The location of your client configuration files

Notes

BuildKit container logs

To display BuildKit container logs (when docker-container driver is used) you have to enable step debug logging or you can also enable debugging in the setup-buildx action step:

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

Logs will be available at the end of a job:

Keep up-to-date with GitHub Dependabot

Since Dependabot has native GitHub Actions support, to enable it on your GitHub repo all you need to do is add the .github/dependabot.yml file:

version: 2
updates:
  # Maintain dependencies for GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"