Thursday, June 18, 2015

Create a Github Project Page with a Custom Domain

I found the instructions on Github to be a little difficult to understand at first as they covered all possibilities.  It turns out to be very easy to create a static website on github and attach a custom domain.

From the top:

For Github

Create a directory on your mac to hold your sites locally - I called mine /pages.

Create a repository on github, it doesn't matter what it is named, but pick a name that will match your domain at some level.

Clone the github repository from your pages directory.

git clone

Go into that directory.

cd repository-name

Create a new branch called "gh-pages".  Use this command:

git checkout --orphan gh-pages

In this directory, create a text file named "CNAME".  Put the url of the domain in it.  That's the only content.  Include the subdomain.  For example:

Create a file called "index.html".  Just to have something there to see.  Put whatever you like in it.


Commit and push this to github.

git add .
git commit -m 'First commit'
git push

Multiple domains?

Just add another repository and follow the same path.

For your registrar

At your registrar, forward your Apex domain to a subdomain, like www.  At godaddy, this was easy enough.  Choose forwarding when managing your domain, choose 301 (permanent) and enter the entire host (

Edit the zone file - create a CNAME where the subdomain ('www' in this case), points to this domain:

Multiple domains?

All domains hosted on github (if you have others) will have a CNAME in the zone file point to the same location at


Wait a little while - at godaddy is was only a couple seconds.  At it took over 24 hours.

Whenever you push your site to github, you will see your updates.

One more thing

Forwarding email

There was one more thing I wanted.  I wanted an email at that domain to forward to my personal email.  So I could temporarily use it and post it on the site.

In Godaddy, there is an easy enough way to forward email.  I used these instructions.  Note, you probably don't need to change the MX records.  I didn't, I just created the forwarding email address and made it a "catch all".

Testing email

And, lastly, you can't test it from the email address you are forwarding to.  This means you need a 3rd email address to test from.  That took a little while to figure out.