GitHub Actions与Docker简介

目录

本指南介绍了如何使用Docker和GitHub Actions构建CI流水线。您将学习如何使用Docker官方的GitHub Actions将您的应用程序构建为Docker镜像并推送到Docker Hub。在本指南结束时，您将拥有一个简单、功能齐全的GitHub Actions配置，用于Docker构建。您可以按原样使用它，或进一步扩展以满足您的需求。

先决条件

如果你想跟随指南操作，请确保你有以下内容：

  • 一个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. 在安全下，转到秘密和变量 > 操作。
  3. 在Secrets下，创建一个新的仓库密钥，命名为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 使用元数据操作的输出来自动应用一致的标签和 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镜像的最佳实践。此配置可以直接使用，也可以根据项目需求扩展其他功能，例如多平台。

进一步阅读