从私有代码库自动部署Hugo站到GitHub Pages

Hugo是个极好的静态网站生成器。一个常见的情况是原始的网站源码放在私有代码库中,但希望自动化构建和部署的功能。假设私有代码库托管在github上,希望能自动化部署到GitHub Pages,这个功能可以通过github actions轻松搞定。

开始之前,假设我们已有了两个repo(可以隶属于不同的github账户):

  • 私有库: 存放网站的源码
  • 目标库: GitHub Pages (xxx.github.io)

需要做的事情就是在目标库创建一个Personal Access Token (PAT),并将其配置在私有库的secret中,再创建一个工作流的yaml即大功告成。

创建Personal Access Token

Personal access tokens (PATs) are an alternative to using passwords for authentication to GitHub Enterprise Server when using the GitHub API or the command line.

创建PAT的主要目的是给私有库访问目标库的权限,可以让私有库的actions推送构建好的代码到目标库中去。

参照 这里 来生成PAT:

Profile Photo -> Settings -> Developer settings -> Personal access tokens -> Generate new token

记得要勾选下面两个scope: workflow and write:packages.

PAT生成好之后,复制下来,妥善保管留待后用,为方便指代,不妨设它为TOKENXXX

注意PAT是一个账户级的token,而且是代开发者使用的,更好的方式是使用deploy key,它是代码库级的token,设置方法类似,本文不再赘述。

在私有库中设置Secret

在私有库中: > Settings -> Secrets -> Actions -> New repository secret

粘贴刚才生成的PAT TOKENXXX 到value框中,并命名这个secret为SECRETNAME

在私有库中创建Action Workflow Yaml

此workflow yaml包括如下几个部分:

  • Checkout: 拉取源码
  • Setup Hugo: 配置Hugo构建环境
  • Run Hugo: 构建网站
  • Deploy: 用 # GitHub Pages Deploy Action 将网站发布到目标库

此workflow是基于 # Using GitHub Actions to Publish Hugo Site From Private to Public Repo 。在私有库如下路径创建 .github/workflows/main.yml:

name: Hugo Build & Deploy - Private to Public

on:
  push:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2.3.4
      with:
        persist-credentials: false

    # Setup Hugo
    - name: Hugo setup
      uses: peaceiris/actions-hugo@v2.5.0
      with:
        hugo-version: 'latest'
        # Download (if necessary) and use Hugo extended version. Example: true
        extended: false

    # Runs Hugo to build the Static Site
    - name: Run Hugo
      run: |
                hugo --verbose

    # Deploy the Static Site to Public Repo (GitHub Pages)
    - name: Deploy
      uses: JamesIves/github-pages-deploy-action@v4.3.3
      with:
        token:  ${{ secrets.SECRETNAME }}
        repository-name: xxx/xxx.github.io
        branch: master # The branch the action should deploy to.
        folder: public # The folder the action should deploy.
        single-commit: true
        commit-message: "Deploy by source"

需要按需配置如下几处:

  • branches: [ master ]: action触发条件,push到master分支上时触发
  • token: ${{ secrets.SECRETNAME }}: 修改这里的SECRETNAME为前文创建的PAT名称
  • repository-name: xxx/xxx.github.io: 目标库的地址,即GitHub Page库的地址

将此yaml checkin,然后,就可以实现向私有库push完之后触发自动构建及部署了:

Hugo Deployment Action

本文谈到的方法同样适用于Hexo,只需要将Setup HugoRun Hugo两个部分替换成Setup HexoRun Hexo即可。