2018 August 14 15:58

This past May, GitHub quietly announced that custom domains hosted on their GitHub Pages service would be available over HTTPS. GitHub has teamed up with the awesome folks at Let’s Encrypt to make this possible.

I tried an experiment to see how easy it is to set up an HTTPS-enabled site from scratch on GitHub Pages. The answer: super easy! And it’s surprisingly fast. Within a minute or two of pushing my tiny site it had a valid SSL cert from Let’s Encrypt!

Here are the steps. NOTE: I’m assuming that you are not a complete Git or GitHub newbie! If you are, the following directions will likely not be enough to get you started. But you are obviously welcome to try anyway!

Register a domain (if you don’t already have one)

Please don’t use Go Daddy, and please don’t register in any of the Donuts, Inc new TLDs. They are creepy and deserve to go down in flames. Because they have purchased United TLD Holdco, those are off-limits too (assuming you agree with me about the creepiness of Donuts.) Sadly that means that one of my favorites among the new TLDs – .rocks – is off-limits.

Ironically – and contrary to ICANN’s unfounded pipe dreams about their new TLD project – .com, .org, and .net are among the cheapest to register now (around $8/year). If you can find a name you like, that is...

As far as choosing a registrar, I’ve had great service from PairNIC (now pair Domains) over the last 18 or so years. (They are the domain registrar branch of pair Networks.) Their service is always improving and their DNS is crazy fast and reliable. They are not the cheapest, but if you buy/renew in 5 year increments they are not bad (I think $13/year or so).

I’ve used Joker a couple of times to register experimental domains (but never renewed any of them). Their prices are good, but their web interface is kind of strange. No problems though.

I’ve got an account with Porkbun, and they have great pricing and offer tons of TLDs, but I can’t comment from experience on using their site to administer a live domain and its DNS. I mean to try this out, and I’ll report back. Porkbun is the registrar arm of Top Level Design, which also runs a few registries (.design, .ink, and .wiki). That’s not an endorsement, just a fact. ;-)

gandi.net is also a good option – lots of TLDs to choose from, and fairly cheap.

You probably have a favorite registrar anyway, so don’t listen to me. ;-)

In the instructions that follow, I am going to assume that you registered the domain “wiki.kiwi”.

Register with GitHub, if you haven’t already

This part is pretty easy. Of course, you’ll have to know some basics of using Git for the rest of these instructions to make much sense. That part is not so easy. It took me – in 2007, when I first started using Git – about six months of reading and pondering before I had the guts to just dive in. But I’ve been super happy that I took the plunge. Git has problems – the UI can be rather odd in places – but it’s crazy powerful, and I personally have never lost any work because of Git. To the contrary – it has saved my butt more than once.

Create a repository on GitHub for your site

If you want this to be your “personal” site or blog, or an “organization” site or blog, name it <username>.github.io (for a personal site) or <orgname>.github.io (for an organization). Your site will live in the master branch of the repo. Read the GitHub Pages docs for more details about the different kinds of sites.

If you already have a project that you are hosting on GitHub and want to create a documentation site for it, create a “gh-pages” branch, as described below.

If you already have a personal or organization site, and you just want to try something new on a different domain, create a repository as if for a project, create a README file as a placeholder, and then follow the “gh-pages” directions below.

Clone the new repo, or existing project repo, onto your machine

On the repository page, copy the “clone this repo” link and then do

  git clone <url>

on your machine. cd into the directory that was just created. If this is a user or organization site, we will stay on the master branch. If this is a project or “random other domain” site, we need to create and populate a “gh-pages” branch.

Prepare the “gh-pages” branch

Skip this part if you are using a user or organization repo.

In the top-level directory of the cloned repo, do the following:

  git checkout --orphan gh-pages
  git rm -rf .

This leaves you with an empty tree, and a “gh-pages” branch with no parents.

Populate the new site

Still in that top-level directory, do this:

  touch .nojekyll

I’m assuming for now that you are going to create a simple HTML site, or you are using some kind of site generator other than Jekyll.

Assuming that you just registered the domain wiki.kiwi, create a file called CNAME with the single line


This will be the root URL of your site.

To have something show up on your new site, create a simple index.html file. Then do

  git add .
  git commit -m "initial commit of new site!"
  git push --all

The --all is only necessary for site using a gh-pages branch. You can leave it off for a user or org site.

Set up some DNS

You’ll want to create a CNAME record with your registrar/DNS provider that maps www.wiki.kiwi to <username>.github.io (or <orgname>.github.io, if you are doing this in an organization account).

That’s all you’ll need to get started. If you are interested in having the bare (or “apex”) domain also resolve, follow GitHub’s directions.

Enjoy your new site!

Go to http://www.wiki.kiwi/ or https://www.wiki.kiwi/ (the http version should redirect to the https version) and marvel! If nothing shows up at first, try again in a minute or two.

While that may seem like a lot of steps, they are all pretty easy. Populating and maintaining your new site is much harder. Witness the state of this site, for example. ;-)

Above all, enjoy!