Setting up a hexo/gitlab publication workflow

Posted on Views:
How to implement a GitLab CI/CD pipeline to publish a (well, this) hexo-based blog

I wanted to set up an automated workflow for publication of this blog. There are several reasons for this:

  • I’m an infrastructure person by nature, I like automating things
  • It’s an opportunity to learn a few new things

I describe below how I set up the machinery so that:

  • The blog is within a git repo on GitLab, and hosted in GitLab pages
  • Pushing to GitLab will rebuld the pages automatically
  • I use my own domain name for the blog
  • I use my own runner (within my home network) for CI/CD

Principles

I specifically wanted to use Gitlab Pages as a hosting platform (at least initially) because I wanted to get to know GitLab’s CI in more detail. One consequence of this is that I would need to use a Static Site Generator.

With those principles fixed, the next question was which SSG to use. GitLab seems to have good support for most options, with Jekyll, Hugo and Hexo leading the way. I chose Hexo for no particular reason, and built my first setup from that.

Start local

I highly recommend following the hexo documentation to get a local copy of your blog working – this also gives you the necessary file skeletons and proves you have a ‘working’ website.

Once you’ve done that, set up your git repo on GitLab and connect to your local files. You should get a standard .gitignore file which looks like this (and keeps the clutter out of your repo):

1
2
3
4
5
6
7
8
.DS_Store
Thumbs.db
db.json
debug.log
node_modules/
public/
.deploy/
themes/

Setting up CI/CD

GitLab’s pipelines are defined in a file called .gitlab-ci.yml in the root directory of your project. The example files I found online all had issues, but a combination of them worked. Particular challenges were:

  • The pipeline didn’t even seem to start, not actually sure what fixed this.
  • The pipeline ran, but failed to generate the pages – replace the image with a modern node version (I chose 16-buster as that is what I was using in a test environment).

The complete .gitlab-ci.yml I ended up with is:

.gitlab-ci.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Full project: https://gitlab.com/pages/hexo
image: node:16-buster

pages:
  script:
    - npm install hexo-cli -g
    - test -e package.json && npm install
    - hexo generate
  artifacts:
    paths:
      - public
  cache:
    paths:
      - node_modules
    key: project
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
Edited 2021-06-28 - See this post on how to control when the pipeline is triggered.

Setting up your own runner

GitLab generously provides a monthly quota of free minutes to all users (thanks!). I specifically wanted to understand how to set up my own runner and this turned out to be trivially easy (with no need to forward ports through my firewall or anything), which means I don’t need to use any of that quota. The best instructions are actually in Project Settings -> CI/CD -> Runners under “Show Runner Installation Instructions”. I chose “docker” as an execution method and used a computer I have running anyway.

Using your own domain

I am hosting this blog as a project (personal-blog) in Gitlab, so it’s canonical URL is https://ax42.gitlab.io/personal-blog. This works fine, linking up my own domain proved harder. Some gotchas:

  • If your Pages site is not publicly visible, GitLab cannot provision the Let’s Encrypt certificate. Note you can set your visibility permissions so that only the Pages are visible to the public (not the code or other features of GitLab).
  • Follow the advice in GitLab’s documentation on having correct A records.
  • Set up your _config.yml as
    _config.yml
    1
    2
    3
    # Full project: https://gitlab.com/pages/hexo
    url: https://<your domain>/<gitlab project>
    root: '/'
    I don’t know why this last point works. I would expect to have to have /personal-blog/ as the root entry.

Helpful odds and bobs