設定您的 GitHub Actions 建構器

目錄

本頁面包含在使用我們的 Setup Buildx Action 時設定 BuildKit 執行個體的說明。

版本鎖定 (Version pinning)

預設情況下，該 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

日誌將在任務結束時提供

BuildKit container logs

BuildKit 常駐程式 (Daemon) 設定

如果您使用 docker-container 驅動程式（預設值），可以透過 config 或 buildkitd-config-inline 輸入參數為您的建構器提供 BuildKit 設定。

映像檔鏡像站 (Registry mirror)

您可以使用 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 內在的限制：您只能在輸入欄位中使用字串。

名稱類型描述
nameString節點名稱。如果留空，則為其所屬建構器的名稱，並加上索引編號後綴。如果您想在工作流程的底層步驟中修改/刪除節點，設定此名稱非常有用。
端點 (endpoint)String要新增至建構器的節點的 Docker context 或端點。
驅動選項 (driver-opts)列表 (List)其他驅動程式特定選項的列表。
buildkitd 旗標Stringbuildkitd 常駐程式的旗標。
platformsString該節點的固定平台。若非空白，這些值將優先於自動偵測到的平台。

以下是使用 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:// 設定身份驗證。

  • 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 }}

獨立模式 (Standalone mode)

如果您的 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 .

隔離建構器

以下範例展示了如何為不同的任務選擇不同的建構器。

此功能在 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
© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.