設定您的 GitHub Actions 建置器

目錄

此頁面包含使用我們的 設定 Buildx Action版本鎖定

根據預設，此動作會嘗試使用 GitHub Runner (建置用戶端) 上可用的最新版 BuildxBuildKit

- 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 設定 Buildx

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 Daemon 設定

如果您使用具有 `config` 或 `buildkitd-config-inline` 輸入的 `docker-container` 驅動程式 (預設)，您可以提供 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字串節點的名稱。如果為空，則為其所屬建置器的名稱，並加上索引號碼後綴。如果您想在工作流程的後續步驟中修改/移除節點，設定此名稱會很有用。
endpoint字串Docker context 或 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 執行個體。為了簡化工作流程中的整合，您可以使用環境變數，使用 BuildKit 用戶端憑證為 tcp:// 設定驗證。

<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