GitHub Actions 與 Docker 入門

目錄

本指南介紹瞭如何使用 Docker 和 GitHub Actions 構建 CI 管道。您將學習如何使用 Docker 官方的 GitHub Actions 將您的應用程式構建為 Docker 映象並將其推送到 Docker Hub。在本指南結束時，您將擁有一個簡單、實用的 Docker 構建的 GitHub Actions 配置。您可以直接使用它，也可以根據您的需求進行擴充套件。

先決條件

如果您想跟著本指南操作，請確保您具備以下條件：

  • 一個 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 中使用：

  1. 開啟您倉庫的 Settings（設定）。
  2. 在 Security（安全）下，轉到 Secrets and variables > Actions（金鑰和變數 > Actions）。
  3. 在 Secrets（金鑰）下，建立一個名為 DOCKER_PASSWORD 的新倉庫金鑰，其中包含您的 Docker 訪問令牌。
  4. 接下來，在 Variables（變數）下，建立一個名為 DOCKER_USERNAME 的倉庫變數，其中包含您的 Docker Hub 使用者名稱。

設定您的 GitHub Actions 工作流

GitHub Actions 工作流定義了一系列自動化任務的步驟，例如響應提交或拉取請求等觸發器來構建和推送 Docker 映象。在本指南中，工作流專注於自動化 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

這些步驟準備元資料，以便在構建和推送過程中為您的映象新增標籤和註釋。

  • 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（軟體物料清單）和來源證明可提高安全性和可追溯性，確保您的映象符合現代軟體供應鏈的要求。

透過少量額外配置，您可以配置 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

有關證明的更多詳細資訊，請參閱文件。

結論

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

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 映象的最佳實踐。此配置可以按原樣使用，也可以根據您專案的需求進行擴充套件，例如新增多平臺支援。

進一步閱讀