Github Action + 基于 Github Page Blog 自动发布

1、什么是 Github Action ?
#

GitHub Actions 是 GitHub 提供的一项持续集成和持续交付（CI/CD）服务，允许开发者在代码库上自动化各种任务。

简单来说，你可以把 GitHub Actions 想象成在你的 GitHub 代码仓库里的一个机器人，并且可以根据你给它设定的规则，自动完成一系列任务（Workflow），主要目的就是服务于这个项目（代码仓库）。

2、基本概念
#

Workflow（工作流程）：定义了一系列要自动执行的过程。详情可以见第三节。
Event（事件）：触发 Workflow 工作流的动作，例如 push、pull request、release 等。详情可见官方文档。
Job（任务）：一个 Workflow 由一个或多个 Jobs 构成，一次 Workflow 的运行，可以完成多个 Jobs。
Step（步骤）：每个 Jobs 由多个 Step 构成，一步步完成。
Action（动作）：每个 Step 可以依次执行一个或多个命令（Action）。

event(触发) -> workflow -> job -> step -> action

3、例子：Github Page 静态博客自动发布
#

使用 Github Action 构建博客自动发布流程。

之前手动发布静态的博客文件，需要切换到 public/ 目录进行 push，更新 Github page 界面

是否可以在 push到博客原文件仓库的时候，自动更新 Github Page（Blog）界面呢？

1. 配置 workflow 文件
#

GitHub Actions 的配置文件叫做 workflow 文件，存放在代码仓库的 .github/workflows 目录。

workflow 文件采用 YAML 格式，文件名可以任意取，但是后缀名统一为 .yml，比如 blog.yml。

一个库可以有多个 workflow 文件。GitHub 只要发现 .github/workflows 目录里面有 .yml文件，就会自动运行该文件。

自动发布示例配置如下：

name: Automatic Blog Publishing

on:
    push:
    schedule:
        # Runs everyday at 8:00 AM
        - cron: "0 0 * * *"

jobs:
    publish:
        name: auto publish blog
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4
              with:
                  submodules: true
                  fetch-depth: 0

            - name: Setup Hugo
              uses: peaceiris/actions-hugo@v2
              with:
                  hugo-version: "latest"

            - name: Build Web
              run: hugo

            - name: Deploy Web
              uses: peaceiris/actions-gh-pages@v3
              with:
                  PERSONAL_TOKEN: ${{ secrets.AUTO_PUBLISH_BLOG_TOKEN }}
                  EXTERNAL_REPOSITORY: LcenArthas/LcenArthas.github.io
                  PUBLISH_BRANCH: main
                  PUBLISH_DIR: ./public
                  commit_message: ${{ github.event.head_commit.message }}

下面针对上面的 workflow 配置文件，解释其中用到的字段。

workflow 文件字段非常多，详见 官方文档

1. name 字段
#

是 workflow 的名称。如果省略该字段，默认为当前 workflow 的文件名。

name: Automatic Blog Publishing

2. on 字段
#

指定触发 workflow 的条件，通常是某些事件。下面代码指定，push 事件触发 workflow。

完整的事件列表，请查看官方文档。

on.schedule 字段
除了代码库事件，GitHub Actions 也支持定时运行。注意，时间是使用 POSIX cron 语法将工作流计划为在指定的 UTC 时间运行。

on:
    push:
    schedule:
        # Runs everyday at 8:00 AM (UTC 0:00 AM)
        - cron: "0 0 * * *"

3. job 字段
#

workflow 文件的主体是jobs字段，表示要执行的一项或多项任务。需要给出每一项任务的 job_id，具体名称自定义，例如我们设置了一个 publish 任务。

jobs.<job_id>.name 字段
是任务的说明，可以任意写。

jobs.<job_id>.runs-on 字段
是指定运行所需要的虚拟机环境。它是必填字段。目前可用的虚拟机见官方文档

jobs:
    publish:
        name: auto publish blog
        runs-on: ubuntu-latest

4. jobs.<job_id>.steps 字段
#

是指作业包含一系列任务，称为 steps。步骤可以运行命令、运行设置任务，或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。
每个 Job 可以包含一个或多个步骤。

jobs.<job_id>.steps.name字段
是指步骤名称。

jobs.<job_id>.steps.uses 字段
是指可以使用在与工作流、官方actions、官方actions市场或者已发布的 Docker 容器映像相同的存储库中定义的操作。

jobs.<job_id>.steps.with 字段
是指某些操作需要必须使用 with 关键字设置的输入。得看具体引用的工作流需要的参数。

下面逐步分析每个步骤的作用

steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
          submodules: true
          fetch-depth: 0

上面是引用了 GitHub Action Checkout @v4版本这个工作流。

它通常是许多工作流的第一步，用于获取源码（将仓库的内容检出到运行工作流的虚拟机上，使得后续步骤可以访问和操作代码。）

submodules：true，会检出子模块，即我们的主题模块。
fetch-depth: 0，指定检出的提交历史记录深度。默认是 1，即只检出最新的提交。设置为 0 表示完整检出所有历史记录。

例如：

- name: Setup Hugo
  uses: peaceiris/actions-hugo@v3
  with:
      hugo-version: "latest"

上面是引用了 GitHub Action Hugo setup @v3版本这个工作流。
作用是安装指定版本的 Hugo 静态站点生成器。

例如：

 - name: Build Web
    run: hugo

这一步骤执行了 hugo 命令，用于运行 Hugo 命令来构建网站。

例如：

- name: Deploy Web
  uses: peaceiris/actions-gh-pages@v4
  with:
      PERSONAL_TOKEN: ${{ secrets.AUTO_PUBLISH_BLOG_TOKEN }}
      EXTERNAL_REPOSITORY: LcenArthas/LcenArthas.github.io
      PUBLISH_BRANCH: main
      PUBLISH_DIR: ./public
      commit_message: ${{ github.event.head_commit.message }}

上面是引用了 GitHub Action GitHub Pages action @v4版本这个工作流。
作用是用于将生成的静态网站部署到 GitHub Page。

EXTERNAL_REPOSITORY: LcenArthas/LcenArthas.github.io，指定要将内容部署到的外部仓库。
PERSONAL_TOKEN: ${{ secrets.AUTO_PUBLISH_BLOG_TOKEN }}，用于认证的 GitHub 个人访问令牌，通常通过 GitHub Secrets 管理。
commit_message: ${{ github.event.head_commit.message }}，使用触发工作流的提交信息作为部署的提交信息。这样可以保留提交历史的上下文信息。
PUBLISH_BRANCH: main, 指定要推送到的目标分支，如果不想新建分支，指定 Github Page 的主分支（main/master）

5. 如何创建 secrets.AUTO_PUBLISH_BLOG_TOKEN
#

要在 GitHub 账户下 Setting - Developer setting - Personal access tokens 下创建一个 Token。权限需要开启 repo 与 workflow。

配置后复制生成的 Token（注：只会出现一次, 推荐另存一个地方）
Make sure to copy your personal access token now. You won’t be able to see it again!
然后在我们博客源仓库的 Settings - Secrets - Actions 中添加 Token，粘贴在 Secret 中，Name 随便起一个，但是注意要和 PERSONAL_TOKEN: ${{ secrets.AUTO_PUBLISH_BLOG_TOKEN }} 后面的AUTO_PUBLISH_BLOG_TOKEN 一致，这样 GitHub Action 就可以获取到 Token 了。