Setting Up a gh-pages Custom Domain

Zachary Newton Avatar by Zachary Newton
on May 12, 2017

Custom domains are great! They allow us to connect to our users in a much nicer way. If you are hosting your project with GitHub, I am sure that you aren’t too fond of the URL that they give you.


So you want to know how to use a custom Apex domain with your GitHub hosted project. Luckily this is a fairly simple task. Before we get started, you are obviously going to need a domain name and your repository on GitHub. There are a few main steps that we need to complete — let’s get it done.

For the lazy people who don't want to read.

Step 01.

  1. Go to your repository on GitHub and click on the “Settings” tab located under your repository’s name.
  2. Scroll till you see “Custom domain”, then enter your domain name that you wish to use and hit “Save”.

Hey look at that, we are almost done. Just in case you are curious or you need to know if your custom domain is supported at GitHub, you can read, “About supported custom domains”.

Step 02.

  1. Go to your DNS settings that your domain registrar gives you and get ready to create just a couple records.
  2. Create an “A” record that points to these two IP addresses (these IP addresses point to GitHub).
  3. Now you need to create a “CNAME” record. Set the name to “www” and tell it to point to “”, using your GitHub username. If you don’t have a normal user account, read this and make the necessary changes.

That’s it, you’re done! I bet you weren’t expecting it to be that easy. If your custom domain is not working yet, it could take a few minutes, but go ahead and add a file named “CNAME” to the root of your repository and add these two lines replacing “yourdomain” with your actual domain name.

If all else fails and it is still not working, read “Adding or removing a custom domain for your GitHub Pages site“ and see if GitHub can help you figure it out in their spider web of custom domain setup instructions.

Finally, if you see something in this post that is outdated or no longer working, tweet me so I can fix it for you :)

You Might Want To Read...
Life Should I be Writing?

Should I be writing? That is a question that I have asked myself time and time again.

Life My Addiction to Knowledge?

I have a problem. Whenever I start a project or whenever I am informed of one that people wish to bring me on board with, my addiction kicks in.

GitHub Adding SSL to gh-pages

If you are a good web developer and you care about your users, you should have SSL on your website.