GitHub pages is a free static hosting provider that unsurprisingly works well with a git workflow. It enables git push to deploy type workflows. My personal site is a static site built with hugo and deployed to GitHub Pages using GitHub Actions.

GitHub Pages Repo

GitHub Pages expects that you have a repo named something like user.github.io that has static files you want deployed. However, if your site requires any sort of building this doesn't really work for you (at least if you want to automate the build step).

One way around this is to treat your GitHub Pages Repo as the output for your build. You create a separate repo that just has the built static files. You can see the repo for my site at kasuboski/kasuboski.github.io.

You'll notice it just has static html, css, etc. I write the content for this site in markdown however, using Hugo.

Code Repo

The actual content is stored in a separate repo that I'm referring to as the code repo. The repo for mysite is kasuboski/personal-site. This repo should look a little more familiar to anyone who has used Hugo.

The content is under content/posts and is written in markdown. This is the repo that I actually modify and have checked out locally. If I wanted to create a new release of it manually I would build the site and push it to the GitHub Pages Repo with the commands below.

hugo --minify
cp ./public ../kasuboski.github.io/
cd ../kasuboski.github.io
git commit -am "cool new post"
git push origin master

Automatic Deploy with GitHub Actions

I don't really want to mess with multiple repositories locally, especially when one of them is essentially machine generated. GitHub Actions can build the site with Hugo and then push it to the GitHub Pages Repo for me.

The workflow file for this can be found here if you just want to copy it.

The basic steps are: check out the code repo, build the site with hugo, push the files to the GitHub Pages Repo, and notify me of the status using Pushover.

It relies heavily on already available actions. The only prerequisite setup is to make a deploy key for the GitHub Pages Repo and to register an app with Pushover.

You can find a walkthrough of creating a deploy key here.

Configuring a Pushover app is here. You'll need the app token and user token. I added both as secrets on the Code Repo.

Now anytime I push a change to the code repo, GitHub Actions will generate the files, update the GitHub Pages repo and send me a push notification with the status.

What's your personal site setup?