配置您的 GitHub Actions 构建器

本页面包含在使用我们的设置 Buildx 操作时配置BuildKit实例的说明。

版本固定

默认情况下，该操作将尝试使用 GitHub Runner（构建客户端）上可用的最新版本的 Buildx 以及最新版本的 BuildKit（构建服务器）。

要固定到特定版本的Buildx，请使用version输入。例如，要固定到Buildx v0.10.0：

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

要固定到特定版本的BuildKit，请在driver-opts输入中使用image选项。例如，要固定到BuildKit v0.11.0：

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

BuildKit 容器日志

在使用docker-container驱动时，要显示BuildKit容器日志，您必须启用步骤调试日志，或者在 Docker Setup Buildx操作中设置--debug buildkitd标志：

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          buildkitd-flags: --debug
      
      - name: Build
        uses: docker/build-push-action@v6

日志将在作业结束时可用：

BuildKit 守护进程配置

如果您使用的是 docker-container 驱动（默认），您可以通过 config 或 buildkitd-config-inline 输入为您的构建器提供 BuildKit 配置：

注册表镜像

你可以直接在workflow中使用buildkitd-config-inline输入来配置一个注册表镜像：

name: ci

on:
  push:

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

有关使用注册表镜像的更多信息，请参阅 Registry mirror。

最大并行度

您可以限制BuildKit求解器的并行度，这对于低性能机器特别有用。

你可以像前面的例子一样使用buildkitd-config-inline输入，或者如果你想的话，可以使用仓库中的专用BuildKit配置文件，通过config输入：

# .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@v3
        with:
          config: .github/buildkitd.toml

向构建器追加额外节点

Buildx 支持在多台机器上运行构建。这对于在本地节点上构建多平台镜像非常有用，特别是在 QEMU 无法处理的更复杂情况下。在本地节点上构建通常具有更好的性能，并且允许你将构建分布在多台机器上。

你可以使用append选项将节点附加到你正在创建的构建器上。它以YAML字符串文档的形式接受输入，以消除与GitHub Actions内在相关的限制：你只能在输入字段中使用字符串：

Name	Type	Description
`name`	String	节点的名称. If empty, it's the name of the builder it belongs to, with an index number suffix. This is useful to set it if you want to modify/remove a node in an underlying step of you workflow.
`endpoint`	String	Docker 上下文或端点 of the node to add to the builder
`driver-opts`	List	List of additional 特定驱动选项
`buildkitd-flags`	String	buildkitd的标志 daemon
`platforms`	String	Fixed platforms for the node. If not empty, values take priority over the detected ones.

这里是一个使用远程节点的示例，使用了 remote 驱动和 TLS 认证:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - 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 }}

远程构建器的身份验证

以下示例展示了如何使用SSH或TLS处理远程构建器的身份验证。

SSH 认证

要能够使用 docker-container 驱动连接到SSH端点，你必须在GitHub Runner上设置SSH私钥和配置：

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: graviton2
          private-key: ${{ secrets.SSH_PRIVATE_KEY }}
          private-key-name: aws_graviton2
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          endpoint: ssh://me@graviton2

TLS 认证

你也可以设置一个远程的BuildKit实例使用远程驱动程序。为了简化工作流程中的集成，你可以使用环境变量来设置使用BuildKit客户端证书进行认证的tcp://：

BUILDER_NODE__AUTH_TLS_CACERT
BUILDER_NODE__AUTH_TLS_CERT
BUILDER_NODE__AUTH_TLS_KEY

占位符是节点在节点列表中的位置。

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver: remote
          endpoint: tcp://graviton2:1234
        env:
          BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
          BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
          BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}

独立模式

如果您没有在GitHub Runner上安装Docker CLI，Buildx二进制文件将直接调用，而不是作为Docker CLI插件调用。如果您想在自己的托管运行器中使用kubernetes驱动程序，这可能很有用：

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:
          driver: kubernetes
      
      - name: Build
        run: |
          buildx build .

隔离构建器

以下示例展示了如何为不同的工作选择不同的构建器。

一个可能有用的情况是当你使用一个monorepo时，你可能希望将不同的包指定给特定的构建器。例如，一些包可能在构建时特别耗费资源，需要更多的计算能力。或者它们需要一个具备特定能力或硬件的构建器。

有关远程构建器的更多信息，请参阅 remote driver 和附加构建器节点示例。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up builder1
        uses: docker/setup-buildx-action@v3
        id: builder1
      
      - name: Set up builder2
        uses: docker/setup-buildx-action@v3
        id: builder2
      
      - name: Build against builder1
        uses: docker/build-push-action@v6
        with:
          builder: ${{ steps.builder1.outputs.name }}
          target: mytarget1
      
      - name: Build against builder2
        uses: docker/build-push-action@v6
        with:
          builder: ${{ steps.builder2.outputs.name }}
          target: mytarget2