使用 GitHub Actions 新增 SBOM 和來源證明 (Provenance Attestations)

軟體物料清單 (SBOM) 與來源證明 (Attestations) 會新增關於映像檔內容及其建構方式的中繼資料。

使用 docker/build-push-action 第 4 版或更新版本時支援證明功能。

預設來源證明

docker/build-push-action GitHub Action 會在滿足下列條件時，自動為您的映像檔新增來源證明：

如果 GitHub 儲存庫為公開，則會自動為映像檔新增 mode=max 的來源證明。
如果 GitHub 儲存庫為私有，則會自動為映像檔新增 mode=min 的來源證明。
如果您使用 docker 匯出器，或透過 load: true 將建構結果載入到 runner，則不會為映像檔新增任何證明。這些輸出格式不支援證明。

警告
如果您使用 docker/build-push-action 為公開 GitHub 儲存庫中的程式碼建構映像檔，預設附加到映像檔的來源證明將包含建構引數 (build arguments) 的值。如果您錯誤地使用建構引數來傳遞密鑰（例如使用者憑證或驗證權杖）到建構過程中，這些密鑰會暴露在來源證明中。請重構您的建構流程，改用密鑰掛載 (secret mounts) 來傳遞這些密鑰。此外，請記得輪替任何可能已經暴露的密鑰。

最高層級來源證明

建議您使用最高層級的來源證明來建構映像檔。私有儲存庫預設僅新增最低層級的來源證明，但您可以透過將 docker/build-push-action GitHub Action 的 provenance 輸入設定為 mode=max，來手動覆寫來源證明層級。

請注意，為映像檔新增證明表示您必須直接將映像檔推送至登錄庫 (registry)，而不是將映像檔載入到 runner 的本機映像檔儲存區。這是因為本機映像檔儲存區不支援載入帶有證明的映像檔。

name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build and push image
        uses: docker/build-push-action@v6
        with:
          push: true
          provenance: mode=max
          tags: ${{ steps.meta.outputs.tags }}

SBOM

SBOM 證明不會自動新增到映像檔。若要新增 SBOM 證明，請將 docker/build-push-action 的 sbom 輸入設定為 true。

name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build and push image
        uses: docker/build-push-action@v6
        with:
          sbom: true
          push: true
          tags: ${{ steps.meta.outputs.tags }}