GitHubActions-自动化

Megestus2024年3月23日

在这段时间里，使用 GitHub Actions 实现了静态博客的自动化部署。只需将更改推送到 GitHub 仓库，GitHub Actions 就会根据预先设定的配置文件自动执行相关部署操作。属实是非常强大，但还是有些不是很明白其中自动化的过程，接下来将学习记录一下这方面的内容。

然后现在去了解它的一个运作过程。

上述提到使用 actions 实现自动化静态博客部署，
其中静态博客，就是通过生成工具（eg：VuePress、Hugo、hexo 等），直接将作者所书写的博文编译成最终的 html、css、js 等静态文件。然后只需将生成的文件部署在服务器（eg：GitHub、Gitee、自建服务器）上面即可被在互联网中访问。

一般这类静态博客部署的流程是：
- 写一篇 markdown 文章。
- 执行命令生成静态文件，比如 npm run build。
- 将静态文件推送到博客仓库
- 访问网址验证是否成功
- 为了备份你的博客，你可能要将你写博客的项目也推送到仓库。
使用了 GitHub Actions 之后，流程可以简化为：
- 写一篇 markdown 文章。
- 提交到 GitHub。（这一步相当于上面的第 5 步，不需要上传 node_modules 文件夹)
- 结束了

不止博客的部署，任意软件的持续集成，都可以由 GitHub Actions 来完成，比如拉取代码、运行测试、登录远程服务器，发布到第三方服务等。因此 GitHub Actions 是实现自动化发布最便捷的方式了，值得学习和使用。

定一个小目标

然后接下来就来使用一下 actions ，定一个小目标

使用git创建一个私有仓库1 -用于项目仓库，里面有用于生成博客的 md 文件，和生成静态博客的脚手架，比如 VuePress，hexo 等
再创建一个开源仓库2 -用于存放博客的静态资源文件，用于展示博客。

目标就是-写要一篇文章-推送到仓库1，仓库2就自动更新静态资源文件。

我对 GitHub Actions 的理解，GitHub Actions 是一个自动化工具，能够帮助我们自动化开发中的各种任务，比如代码的构建、测试和部署。它是基于事件触发的，意味着你可以设定特定的条件来启动这些自动化任务。
例如：你提交到仓库1后，GitHub会监控到push的变动，然后按照你指定的step顺序执行定义好的action，这些action就包括build生成静态文件，push到你指定的仓库2等动作。

关键组件：

1. 触发事件（Triggers）：

事件是触发 GitHub Actions 工作流的行为，如代码推送或拉取请求。通过在 .github/workflows 的 YAML 文件中定义，我们可以精准控制何时启动自动化流程。
- GitHub Actions 通过定义在 .github/workflows 目录中的工作流文件（通常是 YAML 格式）来配置。
- 工作流可以被多种事件触发，比如代码推送（push）、拉取请求（pull request）、定时事件（cron）、或是 GitHub 上的其他事件。

2. 工作流（Workflows）：

工作流是自动化过程的蓝图，它定义了在哪些事件下，哪些任务应当执行。工作流可以非常灵活，支持在多种环境下运行，满足不同的自动化需求。
- 工作流是一个或多个作业的集合，它描述了哪些任务（steps）在什么条件下运行。
- 工作流文件中，你可以定义环境变量、运行环境（比如 Ubuntu、Windows）、需要的服务（如数据库）等。

3. 任务（Jobs）：

任务是工作流中的独立单元，可以包含多个任务。它们可以配置为并行或串行执行，每个任务都运行在自己的虚拟环境中，保证了任务之间的独立性。
- 每个工作流包含一个或多个任务，任务可以并行或顺序执行。
- 每个任务都会在自己的虚拟环境或容器中运行，独立于其他任务。

4. 步骤（Steps）：

步骤是作业中的基本执行单元，可以是一行命令、一个脚本，或是复用的 Actions。Actions 是社区共享的代码片段，可以帮助我们完成特定的任务，如代码部署、环境设置等。
- 每个作业由一系列步骤组成，步骤可以执行命令、运行脚本或使用 Actions。
- Actions 是 GitHub Actions 的核心，可以是自定义的或是社区分享的重用代码片段，用于完成特定的任务，比如检出代码、设置 Node.js 环境、部署到云平台等。

5. 结果和反馈：

工作流运行完毕后，GitHub 会提供执行结果，帮助我们快速定位成功或失败的原因。通过日志分析，我们可以有效地调试和优化工作流。

实战演习

1.创建好仓库

仓库2 开源
仓库1 私有

这里就使用vuepress为例子，使用hope主题。

我们不需要git仓库初始化

然后把 仓库1先克隆到本地-然后把vuepress的根目录文件全部拷贝到 仓库1本地克隆的位置

在这里构建会有个vuepress-vite.js的模块丢失的报错 -点击跳转

随后我们看到 .github/workflows/deploy-docs.yml文件这就是 GitHub Actions 功能的配置文件。

name: 部署文档

on:
  push:
    branches:
      # 确保这是你正在使用的分支名称
      - main

permissions:
  contents: write

jobs:
  deploy-gh-pages:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          # 如果你文档需要 Git 子模块，取消注释下一行
          # submodules: true

      - name: 安装 pnpm
        uses: pnpm/action-setup@v2
        with:
          run_install: true
          version: 8


      - name: 设置 Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: pnpm


      - name: 构建文档
        env:
          NODE_OPTIONS: --max_old_space_size=8192
        run: |-
          pnpm run docs:build
          touch src/.vuepress/dist/.nojekyll

      - name: 部署文档
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          # 这是文档部署到的分支名称
          branch: gh-pages
          folder: src/.vuepress/dist
          # 推送到别的仓库
          token: ${{ secrets.ACCESS_TOKEN }}
          repository-name: Megestus/Detop2

YAML 格式

GitHub Actions 工作流需要的全部内容，遵循 YAML 格式，这里我做一个大致的说明：

on 表示触发条件
jobs 表示要做的工作
- jobs 下的 step表示要做的步骤，前一步失败，后面不会继续执行。
  - step 下有 name、uses、with 等，表示一个 action。
    - name 表示 action 的名称，uses 表示使用哪个插件，with 表示传给插件的参数。
    - uses 中用的就是别人写好的插件，持续集成由很多操作组成，比如抓取代码、运行测试、登录远程服务器，发布到第三方服务等等，这些操作都用共性，GitHub 就允许其他人把写好的插件共享到插件市场供其他人使用，因此如果你需要某个 action，不必自己写复杂的脚本，直接引用他人写好的 action 即可.
    - secrets.XXX 这个 XXX 表示本仓库的环境变量，配置在仓库设置里面的 secrets 菜单拦，都是加密的。

上述文件先别着急 push，一旦 push，这些 actions 就会执行，在参数正确的配置之前，报错那是肯定的。

接下来说一下一些参数的意义以及如何确定这些参数的值。

secrets.ACCESS_TOKEN

对应的配置代码：

      - name: 构建文档
        env:
          NODE_OPTIONS: --max_old_space_size=8192
        run: |-
          pnpm run docs:build
          touch src/.vuepress/dist/.nojekyll

      - name: 部署文档
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          # 这是文档部署到的分支名称
          branch: gh-pages
          folder: src/.vuepress/dist
          token: ${{ secrets.ACCESS_TOKEN }}
          repository-name: Megestus/Depot2

步骤分析

这段 GitHub Actions 工作流配置包含了两个主要的步骤：构建文档和部署文档。下面是每个步骤的分析：

构建文档:
- 作用: 这个步骤使用 pnpm 命令来构建你的文档网站，可能是使用 VuePress 或类似的静态网站生成器。
- 环境变量 NODE_OPTIONS: 设置了环境变量 NODE_OPTIONS 为 --max_old_space_size=8192，这意味着在这个步骤中，Node.js 的进程将被允许使用最多8192MB（8GB）的旧生代内存空间。这通常用于避免构建过程中因内存不足而失败。
- 命令:
  - pnpm run docs:build：运行定义在 package.json 中的 docs:build 脚本来构建文档网站。
  - touch src/.vuepress/dist/.nojekyll：通过 touch 命令创建 .nojekyll 文件，禁止 GitHub Pages 忽略以 _ 开头的文件和目录。
部署文档:
- 作用: 使用 JamesIves/github-pages-deploy-action@v4 这个 Action 将构建好的文档部署到 GitHub Pages。
- 配置项:
  - branch: 指定要将文档部署到的分支名称，这里是 gh-pages。GitHub Pages 将会从这个分支读取内容并发布网站。
  - folder: 指出构建好的文档存放的目录，这里是 src/.vuepress/dist。这个目录应该是静态网站生成器构建过程的输出。
  - token: 使用 secrets.ACCESS_TOKEN 来认证 GitHub 的操作。这个密钥需要在仓库的设置中配置，它应该具有足够的权限来推送到目标分支。注意，这里使用的是 ACCESS_TOKEN，你需要确保在仓库的 Secrets 中正确设置了这个令牌。
  - repository-name: 指定目标仓库的名称，格式为 用户名/仓库名。在这个示例中，文档将被部署到 Megestus/Depot2 仓库的 gh-pages 分支。

这个配置的目的是自动化构建和部署文档到指定的 GitHub 仓库分支。

获取Token以及设置GitHub Secrets

这个 ACCESS_TOKEN 是访问 GitHub API 的令牌，
可以在 GitHub 主页，点击个人头像，Settings -> Developer settings -> Personal access tokens 进行生成或更新，
第一次生成后你可以看到这个令牌，ghp_xxxx ，然后再也不会显示，因此你需要记下来。

然后打开仓库1的设置页面，设置 secrets，加入环境变量

name 是 ACCESS_TOKEN
value 是 ghp_xxxx

如下图所示：

注意
GitHub Secrets 设置：ACCESS_TOKEN 需要在触发 GitHub Actions 工作流的仓库内的 Secrets 设置中进行设置。这意味着如果你的工作流配置文件位于当前仓库（Depot1），并且你希望从这个仓库部署到目标仓库（Depot2），那么你应该在 Depot1 的 Secrets 中设置 ACCESS_TOKEN。

2.上传并推送

修改vuepress的访问根目录

由于演示使用的是 Depot1 和 Depot2 github pages 是需要仓库开源的，那么构建的目录就会出现在Depot2 ，因此pages会发布到 https://megestus.github.io/Depot2/ 中。

我们需要在\src\.vuepress\config.ts里修改配置文件,把base选项由"/"改为"/Depot2"。

import { defineUserConfig } from "vuepress";
import theme from "./theme.js";

export default defineUserConfig({
  base: "/Depot2",

  lang: "zh-CN",
  title: "博客演示",
  description: "vuepress-theme-hope 的博客演示",

  theme,

  // 和 PWA 一起启用
  // shouldPrefetch: false,
});