需求

自从把网站从 Wordpress 转成 Hugo 并托管在 GitHub 之后,一直使用 Travis CI 来自动编译部署更新。 距离上次更新又过了一年多,昨天想发个牢骚,感叹下时事多艰,结果发现 Travis CI 已经删除我之前的代码库配置。

解决方案

在 Hugo 的官方文档网站看到推荐用 GitHub Actions 来完成类似的工作 link。看起来不麻烦,开干。

规划代码库

GitHub 的每一个账号都可以创建单独的 Pages 站点,但是该代码库必须将可见性设为 Public。如果不希望公开自己网站源文件,就需要合理规划代码库。

创建两个代码库

  • <anyname>.github.io – 这个库用来展示静态页面,anyname 需要是 GitHub 全站唯一名字,必须以 github.io 结尾并设置为 Public 可见,下文以 web 代替。
  • any project name – 这个库的名字随意,下文以 web-code 代替,可以设置为 Private 可见。

创建 Workflow

web-code 代码库的默认 main 分支下,创建 Workflow 的配置文件 .github/workflows/gh-pages.yml,配置内容由 Hugo 官方提供,添加了部分注释:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
name: GitHub Pages

on:
  push:
    branches:
      - main # 网站更新 push 到 web-code 库的 main 分支之后,触发这个 Action
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest" # 默认为最新版本,有特殊需要,可以指定其他 Hugo 版本
          extended: true # 激活 Hugo Extended 特性,部分主题需要打开 Hugo 的这个选项

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }} # 只在 main 分支下被触发
        with:
          #github_token: ${{ secrets.GITHUB_TOKEN }} # 如果只创建一个代码库,把 web-code 和 web 分别放置在不同分支,则可以直接使用免配置的 GITHUB_TOKEN
          deploy_key: ${{ secrets.DEPLOY_TOKEN }} # 如果创建两个代码库,则需要采用 DEPLOY_TOKEN 或者 PERSIONAL_TOKEN 进行身份认证
          external_repository: <your account>/<webname>.github.io # web 代码库
          publish_dir: ./public
          keep_files: false
          publish_branch: main # web 代码库的默认分支
          cname: www.abc.com # 开启自定义域名,在 web 代码库根目录生成 CNAME 文件,需要和 <web 代码库>/settings/pages 里设置的自定义域名匹配

设置 DEPLOY_TOKEN

在终端(Linux/MacOS: terminal; Windows: CMD)生成公私钥

1
ssh-keygen -t rsa -b 4096 -C "<your github email>" -f gh-pages

命令执行后生成私钥 gh-pages,和公钥 gh-pages.pub。 访问 <web 代码库>/settings/keys/new,将 gh-pages.pub 内容复制到 Key 中,Title 随意,需要勾选 Allow write access。 访问 <web-code 代码库>/settings/secrets/actions/new, 将 gh-pages 内容复制到 Value 中,NameDEPLOY_TOKEN

提交代码

将更新的日志提交到 web-code 代码库的 main 分支,推送到 GitHub,就会自动触发编译发布。新版本的 Action 脚本不再使用 docker 构建编译环境,一般只需要 20 秒钟就能在自定义的域名看到新增的日志。