使用 Docker 入门 GitHub Actions

目录

本指南介绍了如何使用 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. 打开您的仓库的**设置**。
  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

这些步骤准备元数据，以便在构建和推送过程中标记和注释您的镜像。

  • **签出**步骤克隆 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 镜像的最佳实践。此配置可以按原样使用，也可以根据项目的需要（例如多平台）扩展附加功能。

进一步阅读