GitHub recently (July-August 2022) made changes to the way in which GitHub Actions worked, which had adversely affected the ability for my gh-pages based workflows to work. As a result, I moved my blog site to Netlify. I actually originally used Netlify a long time ago (like 2018) to host my blog site - however I had moved to GitHub Pages as I had other plans for my Netlify account (i.e. hosting other projects).

So what happened?

Originally GitHub Pages for private repositories would not be counted towards your account’s action minutes and artifact quota, therefore even if I had a 2GB gh-pages repository, that repository would not count towards your accounts artifact quota.

GitHub accounts on the Free plan have a monthly limit of 500 MB for “GitHub Storage (GitHub Actions and Packages)”, and Pro users have a monthly limit of 2GB.

However, changes to the way which GitHub Pages works (whereby it uploads a compressed copy of your gh-pages repository as an artifact before publishing) now choke your account of storage quota.

For me, that meant that a single deployment of my blog’s site (around 3GB) would instantly use up my allotted quota :(

Now what?

Time to migrate to Netlify!

Netlify is a online hosting platform that can serve static files and serverless functions. Whilst serverless functions are pretty cool, I’m only going to use it to serve static content, since my blog is built with Hugo - a static site generator. Eventually I’m planning on migrating from Hugo to something Sapper or SvelteKit - but for now we’ll stick with Hugo

Migrating

Migrating is pretty straight-forwards. Firstly we create a site in Netlify that connects to the blog source repository, then we configure it to build with Hugo. Then we make a few site changes, and after that we do some DNS magic to link everything together!

Importing the repository to Netlify

It’s a very straight-forwards procedure, select the repository and edit the build commands

For my build command, I just concatenated all of the commands that previously existed within my GitHub Actions workflow file. (Update theme, build site, update build hash)

Site Changes

Hugo has a baseURL parameter which dictates what website address corresponds to the root path. For example if my Markdown post contained the link [Wow click here!](/magic), then the link will navigate to [baseURL]/magic. We can change this parameter from the old base URL to the new one.

We should also modify any existing links that reference the old address, more on this later though

DNS Records

I want my blog site to be accessible via blog.featherbear.cc, so we can can add a CNAME DNS record for blog, that points to the default Netlify subdomain (stately-palmier-...).

FYI my domain (featherbear.cc) is registered through Porkbun, a DNS registrar with pretty decent prices.

HTTPS

Netlify also provides a super easy means to set up an SSL certificate, in fact it’s just a single button click away!

Wait but what about links on the internet to your old address?

So the issue with moving website content around, is that references to the content may break and give people 404 errors! For pages that embedded images from my site… well I never intended for my content to be hotlinked, so whatever.. As for links to my blog posts, we have a simple solution, thanks to Netlify supporting custom error pages!

You’ve definitely seen a 404 error page at some point in your life.
Perhaps it was a boring page that just showed “404 PAGE NOT FOUND”, or maybe it was something fun like these ones - These pages are served dynamically by that website’s web server, which renders the error page based on the file’s existence.

For a static site however, we can’t just arbitrarily serve another random file if it the target file doesn’t exist - unless your webserver suports it. Common servers like nginx and apache support the serving of ‘custom error pages’ - likewise so does Netlify (and also GitHub). When you visit a broken URL, you remain on that broken URL - however you see a custom error page - with a little bit of JavaScript we can use this to our advantage! This custom error page is canonically named the 404.html file.

By creating a 404.html file with some redirect logic, we can redirect URLs from the old address to the new one! It should be noted that this won’t work with referenced media content (i.e. <img src="[OLD_SITE]/image.jpg">), but redirection away from that URL will work fine.

Effectively, if I visit https://featherbear.cc/blog/post/migrating-back-from-github-pages-to-netlify, the page won’t exist and the 404.html error page will then redirect me to https://blog.featherbear.cc/post/migrating-back-from-github-pages-to-netlify, where the actual content lives!

FYI, the page won’t exist on the old featherbear.cc/blog address because I unpublished it (since it consumed my entire monthly storage quota)

Conclusion

And there we go! My blog now has a new home at blog.featherbear.cc, and from the looks of it, the builds are actually faster as well (since building doesn’t rely on gh-pages caching)!

So, I could have just made my repository public - and therefore the page artifacts won’t count towards my storage quota… but I’ve been meaning to move away from GitHub Pages anyway because it felt rather slow anyway.

In the future, I’m planning to migrate my blog to a Sapper or SvelteKit site anyway - Netlify has some nice extra features (auth, injection, preprocessing, forms) that might come in use when I end up doing that - so migrating my blog today wasn’t too much of a hassle!

If you notice any old links (featherbear.cc/blog/...) that seem to be broken, do let me know!