使用 Docker 簡介 GitHub Actions

本指南介紹如何使用 Docker 和 GitHub Actions 建置持續整合 (CI) 管線。您將學習如何使用 Docker 官方的 GitHub Actions 將您的應用程式建置為 Docker 映像，並將其推送至 Docker Hub。在指南結束時，您將擁有一個簡單且功能齊全的 GitHub Actions 設定，用於 Docker 建置。您可以直接使用它，或根據您的需求進行擴展。

先決條件

如果您想跟隨本指南進行操作，請確保您具備以下項目：

一個 Docker 帳號。
熟悉 Dockerfile。

本指南假設您具備 Docker 的基本概念，但會針對在 GitHub Actions 工作流程中使用 Docker 提供說明。

取得範例應用程式

本指南與專案類型無關，並假設您擁有一個包含 Dockerfile 的應用程式。

如果您需要一個範例專案來進行練習，可以使用此範例應用程式，其中包含用於建置容器化版本應用程式的 Dockerfile。或者，使用您自己的 GitHub 專案，或是從範本建立新的儲存庫。

#syntax=docker/dockerfile:1

# builder installs dependencies and builds the node app
FROM node:lts-alpine AS builder
WORKDIR /src
RUN --mount=src=package.json,target=package.json \
    --mount=src=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN --mount=type=cache,target=/root/.npm \
    npm run build

# release creates the runtime image
FROM node:lts-alpine AS release
WORKDIR /app
COPY --from=builder /src/build .
EXPOSE 3000
CMD ["node", "."]

設定您的 GitHub 儲存庫

本指南中的工作流程會將您建置的映像推送至 Docker Hub。為此，您必須在 GitHub Actions 工作流程中，使用您的 Docker 憑證（使用者名稱與存取權杖）進行驗證。

關於如何建立 Docker 存取權杖的說明，請參閱建立與管理存取權杖。

一旦準備好您的 Docker 憑證，請將憑證新增至您的 GitHub 儲存庫，以便在 GitHub Actions 中使用：

開啟您的儲存庫的 Settings (設定)。
在 Security (安全性) 下，前往 Secrets and variables > Actions。
在 Secrets (密鑰) 下，建立一個名為 DOCKER_PASSWORD 的新儲存庫密鑰，其中包含您的 Docker 存取權杖。
接著，在 Variables (變數) 下，建立一個 DOCKER_USERNAME 儲存庫變數，其中包含您的 Docker Hub 使用者名稱。

設定您的 GitHub Actions 工作流程

GitHub Actions 工作流程定義了一系列步驟來自動化任務（例如建置與推送 Docker 映像），以回應如提交 (commit) 或提取請求 (pull request) 等觸發條件。在本指南中，該工作流程專注於自動化 Docker 建置與測試，確保您的容器化應用程式在發佈前能正確運作。

在您的儲存庫的 .github/workflows/ 目錄中建立一個名為 docker-ci.yml 的檔案。從基本的工作流程設定開始：

name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:

此設定會在推送到 main 分支時以及提取請求時執行工作流程。透過包含這兩種觸發條件，您可以確保在提取請求合併之前，映像能正確建置。

擷取標籤與註解的後設資料

在您工作流程的第一個步驟中，請使用 docker/metadata-action 來為您的映像產生後設資料。此動作會擷取關於您的 Git 儲存庫資訊（例如分支名稱與提交 SHA），並產生諸如標籤與註解等映像後設資料。

將以下 YAML 加入您的工作流程檔案：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image

這些步驟會在建置與推送過程中，準備好用來標記 (tag) 與註解 (annotate) 您映像的後設資料。

Checkout (檢出) 步驟會複製您的 Git 儲存庫。
Extract Docker image metadata (擷取 Docker 映像後設資料) 步驟會擷取 Git 後設資料，並為 Docker 建置產生映像標籤與註解。

驗證您的登錄檔

在您建置映像之前，請先驗證您的登錄檔，以確保能夠將建置好的映像推送至登錄檔。

若要使用 Docker Hub 進行驗證，請將以下步驟新增至您的工作流程：

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

此步驟會使用在儲存庫設定中設定好的 Docker 憑證。

建置並推送映像

最後，建置最終的生產環境映像並將其推送至您的登錄檔。以下設定會建置映像並將其直接推送至登錄檔。

      - name: Build and push Docker image
        uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}

在此設定中：

push: ${{ github.event_name != 'pull_request' }} 確保只有在事件不是提取請求時才會推送映像。如此一來，工作流程會針對提取請求建置並測試映像，但僅在提交至 main 分支時才推送映像。
tags 與 annotations 會使用後設資料動作的輸出，自動為映像套用一致的標籤與註解。

證明

SBOM（軟體物料清單）與來源證明 (provenance attestations) 可提升安全與追蹤能力，確保您的映像符合現代軟體供應鏈的需求。

透過少量額外設定，您可以將 docker/build-push-action 設定為在建置時為映像產生軟體物料清單 (SBOM) 與來源證明。

若要產生這些額外的後設資料，您需要在工作流程中進行兩項變更：

在建置步驟之前，新增一個使用 docker/setup-buildx-action 的步驟。此動作會配置您的 Docker 建置客戶端，使其具備預設客戶端不支援的額外功能。
接著，更新 Build and push Docker image (建置並推送 Docker 映像) 步驟，啟用 SBOM 與來源證明。

這是更新後的程式碼片段：

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Build and push Docker image
        uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true

關於證明 (attestations) 的詳細資訊，請參閱文件。

結論

結合上一節中概述的所有步驟，以下是完整的工作流程設定：

name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Build and push Docker image
        uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true

此工作流程實作了使用 GitHub Actions 建置與推送 Docker 映像的最佳實作。此設定可以直接使用，或根據專案需求（例如多平台建置）擴展額外功能。