配置 GitHub Actions 构建器

本页包含有关在以下情况下配置 BuildKit 实例的说明使用我们的 Setup Buildx Action。

版本固定

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

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

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

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

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

BuildKit 容器日志

要在使用驱动程序时显示 BuildKit 容器日志，您必须启用 Step Debug 日志记录、或在 Docker Setup Buildx 操作中设置 buildkitd 标志：docker-container--debug

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 驱动程序（默认）和 or 输入，则可以向你的生成器提供 BuildKit 配置：configbuildkitd-config-inline

注册表镜像

您可以直接在工作流，输入为：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 镜像的更多信息，请参阅 Registry 镜像。

最大并行度

您可以限制 BuildKit 求解器的并行度，特别是对于低功率机器很有用。

您可以像前面的示例一样使用输入，也可以使用来自仓库的专用 BuildKit 配置文件（如果需要），输入如下：buildkitd-config-inlineconfig

# .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 不处理的更复杂的情况。在原生节点上构建通常具有更好的性能，并允许您将构建分布在多台机器。

您可以使用该选项将节点附加到您正在创建的生成器。它以 YAML 字符串文档的形式进行输入以消除限制与 GitHub Actions 的内在关联：您只能在输入中使用字符串领域：append

名字	类型	描述
`name`	字符串	节点的名称。如果为空，则它是它所属的生成器的名称，带有索引号后缀。如果要修改/删除工作流基础步骤中的节点，则设置它非常有用。
`endpoint`	字符串	要添加到构建器的节点的 Docker 上下文或端点
`driver-opts`	列表	其他特定于驱动程序的选项列表
`buildkitd-flags`	字符串	buildkitd 守护进程的标志
`platforms`	字符串	修复了节点的平台。如果不为空，则值优先于检测到的值。

以下是使用远程节点和远程驱动程序和 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_<idx>_AUTH_TLS_CACERT
BUILDER_NODE_<idx>_AUTH_TLS_CERT
BUILDER_NODE_<idx>_AUTH_TLS_KEY

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

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 binary 被直接调用，而不是将其称为 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 时，并且您希望将不同的软件包精确定位到特定的构建器。例如有些软件包的构建可能特别耗费资源，并且需要更多计算。或者他们需要配备特定功能的构建器或硬件。

有关远程生成器的更多信息，请参阅远程驱动程序和附加生成器节点示例。

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