GitHub Actions的 CI/CD

GitHub Actions 是一个强大的 CI/CD 工具，适用于自动化各种开发任务。GitHub Actions 的原理是基于事件驱动的自动化流水线工具，通过定义触发条件和执行步骤，可以让项目在特定条件下自动运行一系列操作，比如构建、测试、部署等。

GitHub Actions 的核心组成部分

1. 事件（Events）：

   • GitHub Actions 是由事件触发的，例如代码推送、分支合并、创建 PR、发布 Release 等。事件定义了触发工作流的条件。
   • 例如，on: push 会在代码推送时触发，而 on: pull_request 则在提交 PR 时触发。

2. 工作流（Workflow）：

   • 工作流是由一个或多个任务（Job）构成的 YAML 文件，通常位于 .github/workflows 目录中。
   • 工作流定义了在某个事件触发时应该执行的任务，比如构建、测试、发布等步骤。

3. 任务（Jobs）：

   • 任务是工作流中的一个独立执行单元，每个任务可以包含一系列的步骤（Steps）。任务通常在不同的虚拟机环境上运行，默认是并行执行的，但也可以设置任务之间的依赖关系。
   • 每个任务定义了一个执行环境（如 runs-on: ubuntu-latest），可以在该环境中运行一组脚本或调用外部的 Action。

4. 步骤（Steps）：

   • 步骤是在任务中执行的最小操作单位，每个步骤可以运行 shell 命令或使用已有的 Action（预构建的模块化代码）。
   • 每个步骤都是顺序执行的，后续步骤可以依赖前面步骤的输出。

5. Actions（Action）：

   • Actions 是预构建的模块化代码，用于执行特定任务，如配置环境、部署、发送通知等。GitHub 提供了许多官方 Actions，同时用户也可以发布或使用第三方的 Actions。
   • uses 关键字引用这些 Actions，执行一个特定的功能。

GitHub Actions 的执行过程

1. 事件监听：当 GitHub 发生一个事件（如推送、PR），GitHub Actions 会检查是否有工作流定义了对应的触发条件。

2. 启动工作流：如果事件匹配，GitHub Actions 会启动该工作流，并按配置文件执行工作流中的任务。

3. 分配执行环境：每个任务分配一个独立的虚拟环境（如 Ubuntu、macOS、Windows），并在该环境中执行任务步骤。

4. 执行步骤：每个任务中的步骤按顺序执行，可以包括运行 shell 命令、下载依赖、构建项目等。

5. 处理依赖与数据传递：步骤之间的数据可以通过输出变量共享，任务之间也可以通过 needs 指定依赖关系，完成复杂的自动化流程。

6. 生成报告与输出：工作流完成后，GitHub Actions 会生成详细的运行日志，并报告是否成功完成。管理员可以在日志中查看各个步骤的输出，帮助调试和优化工作流。

GitHub Actions 的运行架构

GitHub Actions 的底层架构使用 GitHub 托管的服务器资源（GitHub-hosted runners）来运行工作流。GitHub 托管的 runners 提供了标准的执行环境，包括操作系统和预安装的软件，支持不同的平台。用户也可以自定义并托管自己的 runners。

GitHub Actions 的主要优势

• 自动化流程：通过工作流文件自动触发代码的构建、测试和发布。
• 模块化、可重用的 Actions：允许用户在不同工作流中重用代码，提高效率。
• 多平台支持：支持多种操作系统环境（Ubuntu、Windows、macOS）。
• 集成与数据共享：支持任务与步骤间的数据共享，方便复杂任务的编排。

✨GitHub Actions 和 vitepress 搭建个人博客

1. GitHub Actions 基础

GitHub Actions 通过工作流（workflow）实现自动化。每个工作流包含触发事件、作业（job）和步骤（step）三个核心要素：

• 触发事件：指定哪些事件会触发工作流，比如 push、pull_request、release 等。
• 作业：一个工作流可以包含多个作业。每个作业可以并行执行，但各步骤是按顺序执行的。
• 步骤：步骤是作业中的具体操作，通常是运行命令或执行自定义的脚本。

2. 创建 GitHub Actions 工作流文件

要开始使用 GitHub Actions，需要在项目中创建一个 .yml 文件，位于 .github/workflows 目录中。

示例 .github/workflows/ci.yml 文件：

https://vitepress.dev/

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行。如果你
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # 构建工作
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消此区域注释
      #   with:
      #     version: 9
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # 部署工作
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        # 输出页面的URL
      - name: Output page URL
        run: echo "Page URL: ${{ steps.deployment.outputs.page_url }}"

url: ${{ steps.deployment.outputs.page_url }} 用于动态地获取部署完成后生成的页面URL。这通常用于在工作流程完成后通知某个地方或某个步骤有关页面的最终URL

3. 定义事件和作业步骤

• 事件定义：on 关键字定义触发工作流的事件，比如 push 到 main 分支时，或创建 pull_request 时触发工作流。
• 作业配置：jobs 关键字定义作业名称和运行环境（runs-on），可以是 ubuntu-latest 或其他环境。
• 步骤执行：steps 中定义了具体执行的步骤，如代码检出、设置 Node.js 版本、安装依赖、运行测试和构建项目等。

4. 使用 GitHub Actions 服务器或自托管服务器

GitHub 提供免费的 Actions 服务器资源，但也可以使用自托管服务器。在 runs-on 配置中，可以选择 GitHub 的服务器（如 ubuntu-latest），或指定一个自托管服务器（self-hosted）。

5. 执行和监控工作流

每当代码被推送到 main 分支时，这个工作流都会自动触发，安装依赖、运行测试、构建项目并准备部署。可以在 GitHub 项目的 “Actions” 标签页中查看每个步骤的执行状态和输出日志，以便调试和监控工作流。

GitHub Actions 中的 uses 关键字

用于指定要使用的 预构建 Actions。这些 Actions 可以执行各种任务（如配置环境、上传文件等），并简化复杂的工作流。以下是您提到的几个常用 Actions 及其用途、最新版本和文档链接。

1. actions/configure-pages

2. actions/setup-node

3. actions/upload-pages-artifact

4. actions/deploy-pages

官方 GitHub Actions 文档

在 GitHub Actions 官方市场中可以找到更多 Actions，查看所有可用 Actions 及其文档：GitHub Marketplace。

✨ 集成到 Docker Hub

为了通过 GitHub Actions 配置 Docker 构建和推送到 Docker Hub，我们可以在原有工作流的基础上添加一个用于构建和发布 Docker 镜像的 docker-publish.yml 文件。该文件会构建 Docker 镜像并将其推送到 Docker Hub。下面是详细配置：

✨ Dockerfile

先创建 Dockerfile 文件，确保 VitePress 站点的构建目录和依赖正确地包含在镜像中。此文件位于项目根目录。

# 使用 Node.js 基础镜像
FROM node:20

# 创建工作目录
WORKDIR /app

# 复制项目文件到容器
COPY . .

# 安装依赖
RUN npm ci

# 构建 VitePress 站点
RUN npm run docs:build

# 启动 nginx 或配置其他静态服务器
# 可以使用 serve 或其他方法来提供静态文件
RUN npm install -g serve
CMD ["serve", "-s", "docs/.vitepress/dist"]

# 开放端口（可以根据需要更改）
EXPOSE 3000

✨ docker-publish.yml

https://github.com/docker/login-action?tab=readme-ov-file
https://docs.docker.com/security/for-developers/access-tokens/

接下来，在 .github/workflows 目录下创建 docker-publish.yml 文件。它定义了 GitHub Actions 工作流，用于构建并推送 Docker 镜像到 Docker Hub。

name: Build and Push Docker Image

on:
  push:
    branches: [main]

  # 允许从 Actions 页面手动触发
  workflow_dispatch:

jobs:
  build-and-publish:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      # - name: Log in to Docker Hub
      #   uses: docker/login-action@v2
      #   with:
      #     username: ${{ secrets.DOCKER_USERNAME }}
      #     password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
          
      - name: Build Docker image
        run: |
          docker build -t ${{ vars.DOCKERHUB_USERNAME }}/vitepress-site:latest .

      - name: Push Docker image
        run: |
          docker push ${{ vars.DOCKERHUB_USERNAME }}/vitepress-site:latest

配置说明

• Dockerfile：用于定义 Docker 镜像的构建过程，先安装依赖并构建站点，使用 serve 工具提供静态文件的服务。
• docker-publish.yml：
  • actions/checkout@v4：从 GitHub 仓库中检出代码。
  • docker/login-action@v2：使用 GitHub Secrets 中存储的 Docker Hub 凭证登录。
  • docker build 和 docker push：构建并推送 Docker 镜像到 Docker Hub，镜像标签为 latest。

设置 GitHub Secrets

将 Docker Hub 用户名和密码添加到 GitHub Secrets：

1. 在 GitHub 仓库中，点击 Settings > Secrets and variables > Actions。
2. 添加以下 Secrets：
   • DOCKER_USERNAME：您的 Docker Hub 用户名
   • DOCKER_PASSWORD：您的 Docker Hub 密码
   • DOCKERHUB_TOKEN：您的 Docker Hub token

配置完成后，GitHub Actions 将在每次推送到 main 分支时，自动构建 Docker 镜像并推送到 Docker Hub。

Variables 部分

1. 在 Settings 页面左侧菜单中找到 Secrets and variables 并点击进入。
2. 在 Variables 标签下，你可以看到所有已定义的变量。
   • DOCKERHUB_USERNAME：您的 Docker Hub 用户名

steps:

具体的工作步骤：

• Checkout code

  • 使用 actions/checkout@v4 动作来检出仓库中的代码。这一步是为了获取将要构建和推送的代码。

• Login to Docker Hub

  • 使用 docker/login-action@v3 动作来登录到Docker Hub。这里使用了仓库变量 DOCKERHUB_USERNAME 和秘密 DOCKERHUB_TOKEN 来提供登录所需的凭证。

• Build Docker image

  • 使用shell命令来构建Docker镜像。构建命令使用了 docker build，并将构建的镜像标记为 ${{ vars.DOCKERHUB_USERNAME }}/vitepress-site:latest。这里的 . 表示构建上下文是当前目录。

• Push Docker image

  • 使用shell命令来推送构建好的Docker镜像到Docker Hub。推送命令使用了 docker push，将标记为 ${{ vars.DOCKERHUB_USERNAME }}/vitepress-site:latest 的镜像推送到Docker Hub。

✨ 编辑 Dockerfile 和 GitHub Actions 工作流文件，提供语法提示和格式检查。以下是一些推荐的资源：

1. Dockerfile 编辑和语法提示

• Dockerfile Linter:

  • Hadolint：一个流行的 Dockerfile 语法检查工具，可以通过命令行或集成到 CI/CD 工具中使用。可以在本地安装并运行，也可以使用其在线版本。

• Online Dockerfile Editor:

  • Dockerfile Generator: 提供简单的在线 Dockerfile 编辑和生成工具，能够快速构建 Dockerfile 结构。

2. GitHub Actions 编辑和语法提示

• GitHub Actions Toolkit:

  • GitHub Actions Toolkit: 提供了用于创建自定义 GitHub Actions 的工具库，文档中包含许多示例和用法，可以帮助理解 Actions 的语法。

• GitHub Actions Workflow Syntax:

  • GitHub Actions Documentation: 官方文档中提供了完整的 GitHub Actions 语法参考和示例，适合查阅具体的配置项。

• YAML Linter:

  • YAML Lint: 在线 YAML 语法检查工具，可以用来检查 GitHub Actions 工作流文件的格式和语法错误。

3. IDE 和代码编辑器的支持

许多现代的 IDE 和代码编辑器（如 Visual Studio Code）都提供了 Dockerfile 和 YAML（GitHub Actions 使用的格式）语法高亮和补全功能。

• Visual Studio Code:

  • 安装 Docker 扩展：为 Dockerfile 提供语法高亮和提示。
  • 安装 YAML 扩展：提供 YAML 文件的语法检查和自动补全。

• JetBrains 系列（如 IntelliJ IDEA, PyCharm）:

  • 提供内置的 Docker 和 YAML 支持，可以进行 Dockerfile 和 GitHub Actions 文件的编辑。

4. 代码片段和示例库

• GitHub 示例库:
  • Awesome Actions：一个集合了许多有用 GitHub Actions 示例的库，可以参考他人的工作流文件。

这些工具和资源可以帮助你更轻松地编写和验证 Dockerfile 和 GitHub Actions 工作流文件的语法和结构。

GitHub Actions 的虚拟化和容器化

GitHub Actions 的底层支持多种操作系统环境（如 Ubuntu、Windows、macOS），这是因为其架构基于虚拟化和容器化技术，使得其可以灵活地配置和分配不同操作系统的运行环境。以下是 GitHub Actions 底层支持多操作系统环境的核心原理：

1. 基于虚拟化和容器化的运行环境

GitHub Actions 使用虚拟机（VM）和容器化技术来支持不同的操作系统环境，包括 Ubuntu、Windows 和 macOS。这些虚拟化技术使得 GitHub 能够为每个任务分配一个独立的环境，隔离不同工作流的运行，确保安全性和一致性。

• 虚拟机（VM）：GitHub Actions 使用虚拟机来模拟不同的操作系统。比如 Ubuntu 和 Windows 是使用 Azure 的虚拟机来提供，而 macOS 也使用类似虚拟化技术来提供隔离的运行环境。
• 容器化技术：GitHub Actions 也允许用户在工作流中运行容器（Docker），这使得用户可以定义自定义的环境，无论是 Linux 还是其他兼容的系统，进一步增加了灵活性。

2. GitHub-hosted Runners

GitHub 提供了一种叫 GitHub-hosted runners 的服务器池，包含了不同操作系统的运行环境，每次任务运行时会分配相应的 runner。GitHub-hosted runners 是 GitHub 官方管理和维护的，它们会定期更新，并且预安装了开发所需的常用软件和工具，以便不同操作系统的用户都能无缝使用。

• Ubuntu runners：这些是基于 Linux 的虚拟机，提供了最新的 Ubuntu LTS 版本。
• Windows runners：这些基于 Windows Server 操作系统，支持 Windows 特有的命令和开发工具。
• macOS runners：这些运行在 macOS 虚拟化环境中，支持 macOS 原生的开发工具和 SDK，比如 Xcode。

3. 自定义 Self-hosted Runners

GitHub Actions 还允许用户配置 self-hosted runners，即在用户自定义的物理或云端服务器上运行 GitHub Actions 工作流的环境。通过 self-hosted runners，用户可以选择任意操作系统（包括较旧的系统或自定义 Linux 发行版）来配置自己需要的环境。

• 允许自定义硬件配置以满足特定的性能需求。
• 自定义操作系统，能够配置专用的开发或测试环境，适用于特殊的 CI/CD 需求。

4. 任务调度与分发系统

GitHub Actions 底层有一个 任务调度与分发系统，它根据工作流配置文件中的 runs-on 参数来分发任务。这意味着，用户在工作流中指定 runs-on: ubuntu-latest，调度系统就会为其分配一个 Ubuntu 虚拟机，而 runs-on: windows-latest 则会分配一个 Windows 环境。调度系统确保任务在指定的操作系统环境中运行，并且能够进行有效的资源分配和监控。

5. 基于虚拟机快照的快速部署

GitHub-hosted runners 是基于虚拟机快照（或模板）进行快速部署的，这样可以减少启动时间。例如，GitHub 在 Azure 等云服务上预先配置了 Ubuntu、Windows、macOS 环境快照，并安装了开发常用的工具和依赖。每当有新任务触发，系统会从快照中快速启动一个新的虚拟机实例，缩短了用户等待的时间，并且确保所有任务环境的一致性。

6. 跨平台兼容性支持

GitHub Actions 使用的命令行和脚本可以基于不同操作系统进行调整，很多 Actions 也内置了跨平台兼容性支持。这意味着工作流可以在不同系统上运行同一套代码，简化了跨平台的 CI/CD 流程。例如：

• 一些官方的 Actions 会自动检测操作系统并调整命令。
• 用户可以在工作流中使用 if 判断来指定不同系统的命令。

综上

GitHub Actions 通过虚拟化技术、容器化、自定义 runners、任务调度和环境快照等机制，为用户提供了灵活的多操作系统支持，确保不同平台的代码都能顺利在指定环境中运行。