Since 2019 this site has been built with Hugo. Until today
I used a Makefile target, included as an addendum for historical interest. I
decided this morning that I’d switch this over to use GitHub actions and write
up the experience.
This post was going to be substantially longer, presumably containing a load of
stuff about creating a custom GitHub action that used a customised container
with Hugo inside, figuring out how to get the site published to the gh-pages
branch, then committing it and pushing it. I thought committing back to a
different branch in the repository from within the GitHub Actions runtime might
end up being harder than I expected. At any rate, I figured the post would be
quite helpful and fancy.
But it turns out that last
July
GitHub added the ability to use GitHub Actions directly to publish to GitHub
pages,
bypassing the gh-pages branch completely. There is even a template for using
Hugo. Creating a workflow from that template worked first time 👌.
That was quick – and I suggest anyone still using a Makefile target or custom
action switch over. It’s a nice system. I can now publish to the site from a Git
client on my phone. Should I ever want to.
My old Makefile
Included primarily for my own memory of git tricks like how to test the
current branch is clean. The idea is to clone another copy of the repo
somewhere, then build the site into the copy’s gh-pages branch before
committing and pushing the changes from the copy.
The make target first checks that the current branch is committed. Don’t want
to end up publishing something which doesn’t match the commits in the repo. Of
course, the GitHub Action only runs on commits to main so no tricks needed
there.
Then we clone the repository to /tmp/dx13-hugo-deploy. The gh-pages branch
is checked out in that folder – it’s the publish destination. git -C <DIR>
tells git to treat DIR as the working directory. Cleaner than changing the
directory using cd.
I use --filter=blob:none to speed up cloning the repository. It lazily
downloads the blobs when a branch is checked out, meaning that only the blobs
needed for the gh-pages branch are downloaded.
The script next uses hugo to build the site from the main branch into the
folder holding the gh-pages checkout. Then we commit all the changes using a
generic message and push it. GitHub then deploys.
DEPLOYDIR=/tmp/dx13-hugo-deploy
CLEAN=$(shell git status --porcelain)
deploy:
# Check whether there are uncommitted changes; fail if so
test -z "$(CLEAN)"
- rm -rf $(DEPLOYDIR)
mkdir -p $(DEPLOYDIR)
git clone --filter=blob:none \
git@github.com:mikerhodes/dx13-site.git $(DEPLOYDIR)
git -C $(DEPLOYDIR) checkout gh-pages
hugo -d $(DEPLOYDIR) -b "https://dx13.co.uk"
# .nojekyll prevents GitHub running Jekyll
touch $(DEPLOYDIR)/.nojekyll
git -C $(DEPLOYDIR) add .
git -C $(DEPLOYDIR) commit -m "Publish site"
git -C $(DEPLOYDIR) push