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

打开您仓库的 Settings（设置）。
在 Security（安全）下，转到 Secrets and variables > Actions（密钥和变量 > Actions）。
在 Secrets（密钥）下，创建一个名为 DOCKER_PASSWORD 的新仓库密钥，其中包含您的 Docker 访问令牌。
接下来，在 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 镜像的最佳实践。此配置可以按原样使用，也可以根据您项目的需求进行扩展，例如添加多平台支持。

进一步阅读

在 Docker Build GitHub Actions 部分了解更多关于高级配置和示例的信息。
对于更复杂的构建设置，您可能需要考虑 Bake。（另请参阅 Mastering Buildx Bake 指南。）
要了解 Docker 的托管构建服务，该服务旨在实现更快、多平台的构建，请参阅 Docker Build Cloud。