Host Hugo static website on GitHub Pages using Actions and my domain

In a cost-saving exercise I wanted to try host my personal website on a free platform, since the code repository is hosted on GitHub, I decided to look into GitHub pages.

My existing workflow combines three repositories to build the website:

Hugs (Repo) - Contains my Hugo configuration and assets
Blog (Repo) - Contains the blog posts
Hugo-theme (Repo) - Contains the Hugo theme

In order to use GitHub Pages I needed a fourth repository named after my GitHub account: joeheaton.github.io (Repo). This is the repository that will contain final static site’s assets, such as HTML, CSS, etc.. and be hosted on joeheaton.github.io.

GitHub Actions

GitHub Actions are defined in YAML which defines the steps to run against your repo. Github hosts a library of official & community Actions with configurable behaviour, these are useful for common operations such as checkout a git branch, etc.

I used actions/checkout, peaceiris/actions-hugo & peaceiris/actions-gh-pages.

name: github pages
on:
  push:
    branches:
      - main

Here we define what behaviour the Action triggers for, I specified Push, which means the Action is triggered for every git push origin main that hits my repository. Larger projects will probably want to set this to pull_request or one of the many other events.

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Prepare repos 🥣
        uses: actions/checkout@v2
        with:
          submodules: recursive  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

My build process is fairly simple so it’s all grouped in one job called “deploy”. All Actions run in a container, which means we have a choice of Operating System. I don’t have strict requirements so I set this to ubuntu-latest.

steps is where the build process is defined; the first step is to checkout the repo this Action is attached to. In my case this is the hugs repo, and I need to clone each submodule fully.

- name: Checkout joeheaton.github.io to ./public/
  uses: actions/checkout@v2
  with:
    repository: joeheaton/joeheaton.github.io
    ref: gh-pages
    path: ./public
    fetch-depth: 0

I clone another repo, this time it’s the joeheaton.github.io that will host the end result, I clone this into ./public, this means when hugo builds my website it will overwrite the contents of joeheaton.github.io, which I can then commit and push.

- name: Setup Hugo 🧪
  uses: peaceiris/actions-hugo@v2
  with:
    hugo-version: '0.81.0'
    # extended: true

This is all that’s needed to install any version of hugo thanks to the peaceiris/actions-hugo Action.

- name: Prepare environment 🧪
  run: |
    sudo apt-get install -y sassc

- name: Build 🔨
  run: |
    SITE=joeheaton.github.io make css hugo-prod

Since I defined runs-on: ubuntu-latest at the top of my YAML, I can fulfil one of my dependcies using Ubuntu’s package manager, after that I use my Makefile from hugs to invoke sassc & hugo to build the static site! These commands get executed in the container using the run attribute, we can even use sudo to run as root if needed.

- name: Deploy 📦
  uses: peaceiris/actions-gh-pages@v3
  with:
    deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
    external_repository: joeheaton/joeheaton.github.io
    publish_dir: ./public

Lastly we use peaceiris/actions-gh-pages to deploy the modified joeheaton.github.io, cloned to the ./public directory. The Action uses a predefined GitHub Secret called ACTIONS_DEPLOY_KEY to get write access my joeheaton.github.io repository and push the contents of ./public!

Done, now every commit to hugs results in this Action’s YAML being run through from start to finish.

GitHub Secrets

I mentioned the ACTIONS_DEPLOY_KEY which allows the Action to push changes to an external repository, this is how you set that up. I followed this documentation

This will create a new keypair in the current directory, we will add the private key as Secret in the repo with the static site generator, this is done via the web interface and the Secret should be named ACTIONS_DEPLOY_KEY for peaceiris/actions-gh-pages to pick it up by default.

Repository Secrets

Add the public key as a Deploy Key on joeheaton.github.io.

Deploy Keys

Once this is done the Actions on hugs can now push changes to joeheaton.github.io!

Domains & CNAME

To complete replacing my old static site with GitHub Pages I need to map my personal domain to the website hosted on joeheaton.github.io.

On GitHub navigate to your me.github.io repository, go Settings and scroll down to GitHub Pages and set your Custom Domain.

Go to your Domain name’s DNS provider and add a CNAME record pointing to your me.github.io address. Done, you should see your auto-generated GitHub Pages website when you visit your domain!

I haven’t covered enabling HTTPS, you may have noticed there is an option in GitHub to enforce HTTPS for your GitHub Pages custom domain which isn’t checked by default. I didn’t need to go through with this as my website is routed via Cloudflare which enforces HTTPS on my domain. Technically, that might mean Cloudflare is connecting to GitHub insecurely, not sure.

Errata

I realised after setting my blog and hugs repos back to private, that the hugs repo is able to clone itself with the checkout@v2 action because it inherently is allowed access to itself, despite being private, but it cannot access blog.

June 2021 – I’ve since migrated to Hugo’s built-in Sass compiler, instead of installing sassc as part of the build process. I just deleted the sassc stage, and added extended: true to uses: peaceiris/actions-hugo@v2 to .github/workflows/hugo.yml.

GitHub Actions#

GitHub Secrets

Domains & CNAME

Errata#

GitHub Actions

Errata