使用 Docker 簡介 GitHub Actions

目錄

本指南提供使用 Docker 和 GitHub Actions 建置 CI 流程管線的簡介。您將學習如何使用 Docker 官方的 GitHub Actions 將您的應用程式建置為 Docker 映像檔並將其推送至 Docker Hub。在本指南結束時，您將擁有一個簡單、功能齊全的 Docker 建置 GitHub Actions 設定。按原樣使用它，或進一步擴展它以滿足您的需求。

先決條件

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

  • 一個 Docker 帳戶。
  • 熟悉 Dockerfiles。

本指南假設您具備 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. 開啟儲存庫的設定。
  2. 在安全性下，前往密鑰和變數 > Actions。
  3. 在密鑰下，建立一個名為 DOCKER_PASSWORD 的新儲存庫密鑰，其中包含您的 Docker 存取權杖。
  4. 接下來，在變數下，建立一個包含您的 Docker Hub 使用者名稱的 DOCKER_USERNAME 儲存庫變數。

設定您的 GitHub Actions 工作流程

GitHub Actions 工作流程定義了一系列步驟來自動化任務，例如建置和推送 Docker 映像檔，以回應提交或提取請求等觸發器。在本指南中，工作流程著重於自動化 Docker 建置和測試，確保您的容器化應用程式在發布之前正常運作。

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

name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:

此設定會在推送至主要分支和提取請求時執行工作流程。透過包含兩個觸發器，您可以確保映像檔在合併提取請求之前正確建置。

擷取標籤和註釋的詮釋資料

對於工作流程中的第一步，使用 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 儲存庫。
  • 擷取 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' }} 確保僅在事件不是提取請求時才推送映像檔。這樣，工作流程會建置和測試提取請求的映像檔，但僅推送提交至主要分支的映像檔。
  • tags 和 annotations 使用詮釋資料動作的輸出，將一致的標籤和註釋自動套用至映像檔。

證明

SBOM（軟體物料清單）和來源證明可提高安全性和可追溯性，確保您的映像檔符合現代軟體供應鏈要求。

只需少量額外設定，即可設定 docker/build-push-action 在建置時為映像檔產生軟體物料清單 (SBOM) 和來源證明。

要產生此額外詮釋資料，您需要對工作流程進行兩項更改

  • 在建置步驟之前，新增一個使用 docker/setup-buildx-action 的步驟。此動作會使用預設用戶端不支援的額外功能來設定您的 Docker 建置用戶端。
  • 然後，更新建置和推送 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 映像檔的最佳實務。此設定可以按原樣使用，也可以根據您專案的需求使用其他功能進行擴充，例如多平台。

延伸閱讀