配置你的 GitHub Actions 構建器

目錄

本頁面包含使用我們的 Setup Buildx Action 時配置 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 container logs

BuildKit 守護程式配置

如果您使用 docker-container 驅動程式（預設），可以使用 config 或 buildkitd-config-inline 輸入向構建器提供 BuildKit 配置

登錄檔映象

您可以使用 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"]

有關使用登錄檔映象的更多資訊，請參閱登錄檔映象。

最大並行度

您可以限制 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字串節點的名稱。如果為空，則為它所屬的構建器的名稱，帶有索引數字字尾。如果您想在工作流的後續步驟中修改/刪除節點，設定此值會很有用。
端點字串要新增到構建器的節點的Docker 上下文或端點
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 身份驗證

您還可以使用遠端驅動程式設定遠端 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 二進位制檔案，而不是將其作為 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 驅動程式和新增構建器節點示例。

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