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 or the build-push action. By default, the docker-container driver will be used to be able to build multi-platform images and export cache using a BuildKit container.

---

• Usage
• Configuring your builder
• Version pinning
• Customizing
  • inputs
  • outputs
  • environment variables
• Notes
  • nodes output
  • BuildKit container logs
• Using on GHES
• Contributing

Usage

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v3
      -
        # Add support for more platforms with QEMU (optional)
        # https://github.com/docker/setup-qemu-action
        name: Set up QEMU
        uses: docker/setup-qemu-action@v2
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

Configuring your builder

See https://docs.docker.com/build/ci/github-actions/configure-builder/

Version pinning

This action builds images using Buildx and BuildKit. By default, the action will attempt to use the latest version of Buildx available on the GitHub Runner (the build client) and the latest release of BuildKit (the build server).

To pin to a specific version of Buildx, use the version input. For example, to pin to Buildx v0.10.0:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    version: v0.10.0

To pin to a specific version of BuildKit, use the image option in the driver-opts input. For example, to pin to BuildKit v0.11.0:

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

Customizing

inputs

Following inputs can be used as step.with keys:

List type is a newline-delimited string

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

CSV type must be a newline-delimited string

platforms: linux/amd64,linux/arm64

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	List	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
platforms	List/CSV	Fixed platforms for current node. If not empty, values take priority over the detected ones.
config¹	String	BuildKit config file
config-inline¹	String	Same as config but inline
append	YAML	Append additional nodes to the builder

• ¹ config and config-inline are mutually exclusive

outputs

Following outputs are available

Name	Type	Description
name	String	Builder name
driver	String	Builder driver
platforms	String	Builder node platforms (preferred or available)
nodes	JSON	Builder nodes metadata

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

nodes output

[
  {
     "name": "builder-3820d274-502c-4498-ae24-d4c32b3023d90",
     "endpoint": "unix:///var/run/docker.sock",
     "driver-opts": [
       "network=host",
       "image=moby/buildkit:master"
     ],
    "status": "running",
    "buildkitd-flags": "--allow-insecure-entitlement security.insecure --allow-insecure-entitlement network.host",
    "buildkit": "3fab389",
    "platforms": "linux/amd64,linux/amd64/v2,linux/amd64/v3,linux/amd64/v4,linux/386"
  }
]

Name	Type	Description
name	String	Node name
endpoint	String	Node endpoint
driver-opts	List	Options for the driver
status	String	Node status
buildkitd-flags	String	Flags for buildkitd daemon
buildkit	String	BuildKit version
platforms	String	Platforms available

BuildKit container logs

See https://docs.docker.com/build/ci/github-actions/configure-builder/#buildkit-container-logs

Using on GHES

GitHub Runners come pre-installed with Docker Buildx following your virtual environment. If you specify a version or latest of Docker Buildx in your workflow, the version will be downloaded from GitHub Releases in docker/buildx repository. These calls to docker/buildx are made via unauthenticated requests, which are limited to 60 requests per hour per IP.

If more requests are made within the time frame, then you will start to see rate-limit errors during downloading that looks like:

##[error]API rate limit exceeded for...

To get a higher rate limit, you can generate a personal access token on github.com and pass it as the github_token input for the action:

uses: docker/setup-buildx-action@v3
with:
  github_token: ${{ secrets.GH_DOTCOM_TOKEN }}
  version: v0.10.1

If the runner is not able to access github.com, it will take the default one available on the GitHub Runner or runner's tool cache. See "Setting up the tool cache on self-hosted runners without internet access" for more information.

Contributing

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