Setting Up a gh-pages Custom Domain

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.

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 incase 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 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 there spiderweb 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 :)

Originally published at on May 12, 2017.