Cloud Confusing

Explaining hosting, AWS, project management, and all manner of cloud solutions.

While I’m partial to hosting static sites on AWS with S3, there other ways to solve the problem of cheap/free static hosting. One popular option that works for simple one-page sites, single-page applications, Jekyll blogs, and more is GitHub Pages. All you need to get started is a free (or paid) GitHub account, a basic understanding of how git or GitHub works, and about 10 minutes.

As an example of this technique in action, I moved from AWS S3 to GitHub. You can see the repo on GitHub.

Moving a site to GitHub is very easy in practice, but it’s a bit confusing. This is the case not because GitHub provides too little documentation, but rather because the company provides much too much information for what is ultimately a very easy procedure.

Hosting a Site on GitHub in 3 Steps

The core steps are quite simple. In GitHub Pages terms, we will be creating a project site, from scratch, using GitHub Desktop, GitHub site, or command line (the last choice is up to you).

  1. Create a repository in GitHub that holds your site. At the very least you need an index.html file.
  2. Name the repo The name will determine your URL, but this can be overridden if you opt for a custom domain, which we will do.
  3. Go to the repo’s Settings tab. Enable Pages but choosing your Master Branch to be the source of the website. Technically you could use another branch, but it’s simpler to user master.

At this point you should have a working website at You can see that auto-forwards to

That was super easy but what about a custom domain? GitHub provides pages of instructions for this, and while they are all very thorough, it’s more than most of us need for what is essentially a simple operation. Here are the most stripped down steps possible…

Setting a Custom URL for a GitHub Site

You already own the domain name right?

1. Set the A Record

Go you your DNS provider and configure your A records to to point at GitHub’s IPs:


This will setup your apex domain — Each DNS provider will handle these things a little differently, but the main goal is to point your DNS to GitHub.

2. Set Up the www Subdomain

Since you are doing all this work, you might as well tackle the ole’ triple dub as well. This can be accomplished by create a CNAME for the www subdomain and pointing it at @ or

3. Settings Update

Return to your Github repo’s settings and go down to Pages again. Now entire your custom domain name and click the “Enforce HTTPS” buttons (if it’s not already clicked). This will tell GitHub to associate your repo with the incoming DNS traffic.

At this point you should be done. If things aren’t working then you can add a CNAME file (a text files with no .txt extension) to your repo’s root with your naked domain on line 1, like so. This doesn’t seem to be necessary any longer, but if you are troubleshooting it could be worth a shot.

And that’s it, you have a brand new, totally free, static site on GitHub! Sure, your code is fully searchable on the site if you have a free account, but that’s a pretty minor trade-off most of the time.

May 15th, 2018

Posted In: GitHub

Tags: , , ,