配置你的 GitHub Actions 构建器

目录

此页面包含在使用我们的 Setup Buildx Action 时配置你的 BuildKit 实例的说明。

版本锁定

默认情况下，该 action 会尝试使用 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 action 中设置 --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

日志将在 Job 结束时可用

BuildKit container logs

BuildKit 守护程序配置

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

镜像仓库镜像

你可以使用 buildkitd-config-inline 输入，直接在你的 workflow 中使用内联块配置镜像仓库镜像

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"]

有关使用镜像仓库镜像的更多信息，请参阅镜像仓库镜像。

最大并行度

你可以限制 BuildKit solver 的并行度，这对于低性能机器尤其有用。

你可以像前面的示例一样使用 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字符串节点的名称。如果为空，则为其所属构建器的名称加上索引号后缀。如果你想在 workflow 的后续步骤中修改/移除节点，设置此名称很有用。
要添加到构建器的节点的Docker 上下文或端点字符串endpoint
driver-opts列表额外的驱动程序特定选项列表
buildkitd-flags字符串buildkitd 守护程序的标志
platforms字符串节点的固定平台。如果不为空，则值优先于检测到的值。

以下是使用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 身份验证

你还可以使用 remote 驱动程序设置远程 BuildKit 实例。为了简化在 workflow 中的集成，你可以使用设置了 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 二进制文件将直接调用，而不是作为 Docker CLI 插件调用。如果你想在自托管 Runner 中使用 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 .

隔离构建器

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

一个可能有用的示例场景是，当你使用 monorepo 时，并且希望将不同的包指向特定的构建器。例如，某些包的构建可能特别占用资源，需要更多计算能力。或者它们需要配备特定能力或硬件的构建器。

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

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
页面选项