/ #deployment #netlify 

A tiny case study about migrating to Netlify when disaster strikes at GitHub, featuring Cloudflare

Last Monday (22 October 2018) GitHub was going 💥, and scheduled content on Code with Hugo wasn’t going live.

For context, the blog’s setup is documented in “Switching the lights on: Hugo vs Hugo config files”.

tl;dr (as is relevant to this post)

  • Cloudflare DNS + CDN + proxying + HTTPS
  • GitHub Pages
  • Hugo as a static site generator
  • CircleCI to deploy the site daily + on push (🤷‍♀️wasn’t in the post but that’s how I do it)

Contents of this post:

On hosting with a business which isn’t specialised in static hosting 🤔

Back to the story: codewithhugo.com was not building or publishing on GitHub Page… which means my post “Simple but not too simple: how micro improves your Node applications”, scheduled for publication at 7AM UTC (I’ll write up how I do this one day subscribe to get it in your inbox)… Didn’t go live.

As it turns out, the GitHub team itself struggled to get a post out during this period: “We use GitHub Pages internally and all builds had been paused several hours earlier, so publishing this took additional effort.”

What’s worse, GitHub’s web-hooks and other core APIs were either unavailable or really flakey/disrupted. Which means that migrating to Netlify wasn’t as simple as usual: “deploy from git” wouldn’t work due to disruptions on GitHub’s end.

Speedy migration to Netlify ⏩

A great Netlify feature is “manual deploys”, where you just upload a zip and it deploys it as a static site. Thankfully the latest version on my GitHub Pages repository had the post I wanted (it just couldn’t deploy it).

Getting the site up on Netlify was simple enough:

  • download the repository’s zip archive from GitHub (thankfully this wasn’t on fire 🚒 like the rest of GitHub)
  • upload it to Netlify using the dashboard

At this point the site is live on a *.netlify.com domain.

Getting the codewithhugo.com domain pointing to Netlify:

  • Update the A records on Cloudflare’s DNS to Netlify’s load balancer

What surprised me is how fast the update happened. A DNS update should take time to propagate. Except this wasn’t strictly a DNS update since I’m using Cloudflare’s proxied DNS. That means if you dig codewithhugo.com you get the following answer section:

codewithhugo.com.        299        IN        A
codewithhugo.com.        299        IN        A

Suprise! 🎉 those records don’t point to Netlify (or GitHub Pages), they point to Cloudflare (see https://www.abuseipdb.com/whois/ and https://www.abuseipdb.com/whois/ Cloudflare then proxies to Netlify’s load balancer. Super 👏 neat 👏 .

Why use Cloudflare then?

Well since @github Pages stopped building with all the issues, thanks to @Netlify’s zip upload functionality and @Cloudflare’s proxied DNS service I’ve been able to get the blog post I scheduled for today live.


— Hugo Di Francesco (@hugo__df) 22 October 2018

When I first published “Switching the lights on: Hugo vs Hugo config files”, one of the reactions I received was: “You don’t seem to explain any reason for using CloudFlare on top of GitHub pages. Care to elaborate?”.

To which I replied (see the comment here):

  • HTTPS (pretty sure it didn’t use to be a thing with custom domains on GitHub pages)
  • CDN
  • DNS

Which even I didn’t find that compelling, now I guess I do have a compelling reason to use Cloudflare: you’re able to change hosting provider within minutes if you leverage Cloudflare’s proxied DNS + CDN service.

I think due to Cloudflare’s proxying and Netlify’s manual deploy saving my bacon in this instance (Monday is newsletter day and I wanted to get the micro post in there), it’s brought value enough to justify my stack choice.

The path forward

✅ Don't switch back to GitHub Pages #codewithhugo

Since I host my static sites on Netlify now (see “Deployment options: Netlify + Dokku on DigitalOcean vs now.sh, GitHub Pages, Heroku and AWS”), I’ve decided that maybe sticking codewithhugo.com on there permanently is a good idea. Sorry GitHub Pages.

If you want to migrate a HTML @github Pages site to @Netlify here’s an example config (tl;dr: use Publish Directory “.”) pic.twitter.com/pDvlMXnCoc

— Hugo Di Francesco (@hugo__df) 23 October 2018

Here’s an example config for deploying a site hosted on GitHub (that would work as a GitHub Pages site) to Netlify:

Example config to deploy a GitHub Pages site from GitHub to Netlify

Pretty simple, publish the root directory using Publish Directory: . and don’t set a build command.

GitHub Pages is awesome, my demos are likely to still live there. Disruptions happen to everyone but as is clear in their post-mortem, GitHub isn’t a static hosting service 🙂. Netlify’s core business proposition is static site hosting and deployment, that’s why Code with Hugo is going to live there from now on 👍.

unsplash-logoAnthony Cantin


Hugo Di Francesco

A developer, working out of London writing CSS, JavaScript and Python.

Subscribe for Enterprise Node.js and JavaScript Guides

Build your web platform with modern Node.js/JavaScript best-practices, tools and patterns