终于，Github 自己出 CI/CD 工具了，Whoa~

鉴于 Gitlab 等早就有自动构建工具了，Github 已经晚了许多，那 Github Actions 能打得过吗？来上手试一下。

0. 为什么是自动部署 Hexo

个人项目很少会用到 CI/CD 工具，那几乎唯一能用到自动部署的就是静态博客了。

而且折腾 Blog 是咱最喜欢的娱乐活动之一...（写 Blog 不是）

1. Get started

先在 GitHub Actions 申请测试，然后等邮件通知。

咱等了不到一周的样子就收到了开通邮件。

当然，如果是体验 CI 的话，也可以选择其他的工具，比如 Travis CI。 这是之前写的介绍：持续集成与 Travis CI 入门实践，这篇结尾有个链接介绍如何部署 Hexo 的，可以参考。

2. 配置 Hexo

如何安装及配置 Hexo 不是本文重点，请自行查询官方文档。

建议先在本地跑通部署到 Github Pages 以后再继续。

配置完成后，把 _config.yml 里 deploy 的 repo 地址换成 SSH 地址（仓库页面 Clone and Download - Use SSH 里的地址），以便后面用密钥 push 到仓库。

3. 配置仓库及 key

因为用户名 username.github.io 的 Github Pages 仓库只能部署 master 分支，而 Actions 的配置文件需要放在 master 分支（仅为个人猜测，因为放在其他分支出现了问题）。 所以需要再开一个仓库，放本地的源代码以及配置 Actions。

2020-06-06 update: 若不使用 username.github.io 这个仓库，而是在其他名字的仓库使用 Pages 的话，是可以放在同一个仓库的不同分支上的。 Actions 配置文件仅在当前分支上会被触发（source），因此开一个分支 source 里面放源码和 Actions 配置文件是可以的 。详见英文版 Blog 的操作。

新建一个仓库，先不需要初始化。在本地生成一个 key：

1
ssh-keygen -t rsa -b 4096 -C "xiaopc@users.noreply.github.com" -f ~/.ssh/github-actions-deploy

（也可以生成其他种类的 key，如果用上面的命令，需要修改一下用户名）

在新仓库的 Settings -> Secrets 里添加刚刚生成的私钥，名称为 ACTION_DEPLOY_KEY。

然后在 Github Pages 的仓库，Settings -> Deploy keys 添加刚刚生成的公钥，名称随意，但要勾选 Allow write access。

2020-02-19 update: 如果 Github 账号有添加过 SSH key 是可以直接用的（那个 key 有所有仓库的权限），只需要添加 ACTION_DEPLOY_KEY 即可，不需要添加公钥。 但是为了安全起见呢，最好还是新建一个吧 (o=^•ェ•)o

2020-06-06 update: 同一个 Github 账号下不能添加两个相同的 SSH key，也就是说按照上面的方法添加的 key 无法再被添加到另外一个仓库，或是设为账号全局 key。

4. 给源码仓库添加 Actions 配置

可以在网页上 Actions 里编辑配置文件，也可以直接在本地目录添加直接 commit。

网页上可以看到，Github 提供了很多的模板：

对于大部分应用的自动测试构建发布是足够的了，这个相比 Travis CI 降低了一点点门槛。

此外，Actions 还可以将动作打包发布到 Marketplace，这是 Actions 的一个亮点，大大增加了复用能力。

不过要部署 Hexo，现在还没有打包的动作，需要自己写。

如果在网页编辑配置文件的话，选择 Blank workflow。 如果是在本地目录提交配置文件的话，将配置文件存至 .github/workflows/*随便起名*.yml。

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
40
name: Build and Update Github Pages

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      
      - name: Use Node.js 10.x
        uses: actions/setup-node@v1
        with:
          node-version: "10.x"

      - name: Setup Hexo env
        env:
          ACTION_DEPLOY_KEY: ${{ secrets.ACTION_DEPLOY_KEY }}
        run: |
          # set up private key for deploy
          mkdir -p ~/.ssh/
          echo "$ACTION_DEPLOY_KEY" | tr -d '\r' > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          # set git infomation
          git config --global user.name 'xiaopc'
          git config --global user.email 'xiaopc@users.noreply.github.com'
          # install dependencies
          npm i -g hexo-cli
          npm i
          # install pandoc
          curl -s -L https://github.com/jgm/pandoc/releases/download/2.7.3/pandoc-2.7.3-linux.tar.gz | tar xvzf - -C $RUNNER_TOOL_CACHE/

      - name: Deploy
        run: |
          # add pandoc to PATH
          export PATH="$PATH:$RUNNER_TOOL_CACHE/pandoc-2.7.3/bin"
          # publish
          hexo generate && hexo deploy

对这个配置文件做几点说明：

  1. Actions 在早期测试时用的是 HCL 格式，而现在使用 YAML 配置，HCL 格式配置文件已被废弃。YAML 格式需要严格按照缩进。

  2. on 标注什么事件会触发这个 workflow，可以指定 branches，详情参考文档。

  3. runs-on 设置运行平台，目前有 Windows、Ubuntu、macOS，见文档。

  4. uses 是使用打包好的 action，可以通过 with 传参数。官方提供了一些 Git 基本操作和环境安装的包，也可以使用 Docker。

  5. env 可以设置这一步的环境变量，这一步设置的变量不会继承到下一步。刚才设置的私钥可以通过 secrets 模板变量获取到，具体见文档。另外直接将密钥 echo 出来会被打码 :)

  6. 在网页上保存私钥很可能会把 key 存成 CR-LF 换行模式的，而私钥文件要求 LF 模式，要用 tr -d '\r' 去掉回车符。（在这卡了几个小时(ノへ￣、)）[3]

  7. Git 配置请更改为自己的。

  8. 由于咱用了 hexo-renderer-pandoc 引擎渲染 Markdown（LaTeX 公式支持更好），要装 pandoc。 但是没有 root 权限，只能手动装在其他目录。 官方的 toolkit 提供了一个缓存下载内容的工具 actions/tool-cache，但是它仅在一个 workflow 里作用，so...

  9. 上面说的那个工具下载保存目录是 $RUNNER_TOOL_CACHE，这个环境变量没有在文档里，目前值为 /opt/hostedtoolcache。

5. 开始构建

配置好了，commit & push 后在网页查看 build 状态：

6. 尾声

和 Travis CI 相比，Actions 提供的平台更多，扩展性更强，但是缺少像 build cache 这些功能（build 的时候每次都要重新装依赖）。

虽然和它声称的 word-class CI/CD 还有一些距离，但是 Actions 已经比目前免费的工具高到不知道哪里了。

再加上它与 Github 的深度集成，以及 marketplace 仓库，可以发挥 CI/CD 的更多潜能。

对了，Actions 公开仓库免费，私仓按运行时间计费。

本文参考了：

[1] 通过 GitHub Actions 自动部署 Hexo https://gythialy.github.io/deploy-hexo-to-github-pages-via-github-actions/

[2] Deploying Hugo With Github Actions https://cupfullofcode.com/blog/2018/12/21/deploying-hugo-with-github-actions/

[3] .gitlab.ci.yml for SSH with private key https://gist.github.com/yannhowe/5ab1501156bd84c8ac261e2c17b8e3e0