Every 5 years I seem to upgrade my website, in 2012 I upgraded my old static site to a wordpress site, then 5 years later in 2017 I changed to a static HTML website generated by Pelican. This statically generated website was hosted on github pages, this is a setup I liked, with all my website files stored in git and then deployed automatically with github workflows when I merged a pull request with a new post in it.

My reason for upgrading was that I wanted to update my theme, and I couldn’t find anything I liked in the pelican ecosystem, as a result I decided to go with Hugo. This is a static site generator that works well with github pages, and functions with my current workflow of generating my git hosted on github pages.

My workflow is based around posts written in markdown files stored in a github repository. The migration from Pelican to markdown was reasonably simple, although it required manually updating the headers in my markdown posts, and slowly upgrading all the links to match the new structure. Much as before with my old Pelican site the hugo markdown files are stored in one private Git repo, and the static site is deployed to a second git repo, which is a submodule in the output folder. This automatic deployment is handled by a github actions workflow, the workflow file is below.

The start of the github workflow confirms that the workflow is automatically run when there is a push to the master branch, is allows me to make small changes (such as the inevitable spelling errors) directly to master, and then major changes in pull requests, with them all being deployed automatically to the website.

name: Build Site

# Controls when the action will run.
on:
  # Trigger the workflow on push or pull request,
  # but only for the master branch
  push:
    branches:
      - master

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

The workflow then needs to setup all the required git repository, and tools for building the website. The first 3 lines are all about getting the data from the git repository and the required SSH key for adding the updated site, we then print some debug info to the console. The final step is to install Hugo itself, for this we use the pre-made github action, and select the extended version, as it has features needed for the template, we also select the latest version as it is good to be up to date.

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: webfactory/ssh-agent@v0.4.1
      with:
        ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

    - uses: actions/checkout@v1
      with:
        submodules: true

    - name: Checkout submodule
      run: |
        cd output
        git checkout master
        cd ..
    - name: Debug info
      run: |
        echo "REPO: $GITHUB_REPOSITORY"
        echo "ACTOR: $GITHUB_ACTOR"
    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v2
      with:
        hugo-version: 'latest'
        extended: true

With all the tools and files installed we can now complete the main event, building the site is completed with a single command hugo -d output which overwrites the existing site in the github pages directory, that we checked out earlier, the following commands then setup the git user so that a commit can be made from the repo, committing and pushing the latest version of the site up to github page ready for uses to see when they open up my website within a few seconds.

    - name: Build and deploy site
      run: |
        echo '=================== Build site ==================='
        hugo -d output
        echo '=================== Publish to GitHub Pages ==================='
        cd output
        git config user.name "${GITHUB_ACTOR}"
        git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
        git add .
        echo -n 'Files to Commit:' && ls -l | wc -l
        timestamp=$(date +%s%3N)
        git commit -m "[ci] Automated deployment to GitHub Pages on $timestamp"
        git push --force
        cd ../
        echo '=================== Done  ==================='

With that the latest version of my website is deployed everytime I add a new update.