Redirecting GitHub Page to a custom domain
Note: This tutorial requires you to have a domain. If you don’t already have one, you might not be able to really try this out for yourself. But still, this tutorial will make a good read :)
TLDR: Skip the explanation and go straight to the steps
I have plans to migrate my blog to my github account. If everything goes well, you can expect a tutorial on how to setup a blog on there, complete with google analytics and all that.
Setting up a page on github
Each account on GitHub will be allowed one subdomain in the following format:
<username>.github.io. If you already have your content ready on that repository, you can skip this section. If you have no idea what I am talking about, read on.
Sign in and create a new repository. After that, go on to the “settings” tabs of your repository.
Note: Your new repository must have the following name:
<username> is your GitHub handler.
Scroll all the way down to the section where it says “GitHub Pages”. Go on and “launch automatic page generator”. This generator lets you edit the information to your page. Choose a nice layout and save the changes.
What you have just done is to create a new branch
master in your respository and populate it with the generated page. If you go on and see the files available (in the “code” tab), you will see the
index.html sitting there, waiting to be shown to the world.
Basics of DNS settings
If covered in detail, this section can take a whole posts by itself. Instead, I am going to just cover a simple version of it, covering what we will be using in this post.
Types of domains
Before that, let’s cover the few types of domain that GitHub supports. The first type would be apex domain. This is the “main” domain. Examples of such domains would be
google.com. These are one level below the top-level domain (
Then we have subdomains. These are one level down the apex domains, and are usually used to split up your sites into different parts. Examples would include
ongspxm.github.io (see GitHub uses subdomains too).
DNS Record types
There are a few different types of DNS records. These records will point to different resources, then your request will be passed from one resource to another and finally be resolved to an IP address.
Here, I cover the
A record and
CNAME record, which is used in pointing your domain to a certain resource online. No idea what I am talking about? Read on.
A (address) record directs the hostname to a certain IP address. For example, you could have
test.com point to your home computer and serve files out of there. Let’s assume your home computer has the IP address
192.168.0.1. Your record will look something like this:
Name/Host Type Value test.com. A 192.168.0.1
Note that in the host section, there is a trailing
.. It refers to the top level domain. But for the IP address, there isn’t any top level domain to resolve, hence, there is no need for the trailing
The second type of record
CNAME (canonical name), is also known as the alias. This allows you to point different subdomains to different parts of the web. Unlike the
A record, the
CNAME need not be an IP address, it can point to a domain or a subdomain.
The request will follow the resource that the records points to and continue to resolve the request from there.
Name/Host Type Value www CNAME @
This CNAME record redirects the
www subdomain to the apex domain (the
@ symbol is a shortcut many hosting use to refer to the apex domain). So when you go to
www.example.com, it will be resolved to
Changing the settings
Go your GitHub respository, go to “Settings > GitHub Pages”. Let’s say your domain is
example.com. Change your “Custom Domain” to
Now login to your GoDaddy account, and navigate to “Domains > Manage DNS”. You will be brought to a table of records. There will be some of the default record there already. You will see a few
A records, some
CNAME records, and some
NS records (not important for now).
Create a new
CNAME record with
www as the name. Now put in your github pages link as the value. So your record will look something like this.
Host/Name Type Value www CNAME <username>.github.io
Note: If you already have a www
CNAME record, you can edit it to point to your GitHub Page.
Check if it is working
For those who are used to setting up network, working with DNS, you will probably be familiar with “dig” (DNS information groper). For those of you starting out, there is an online version that you can use to check your settings.
Now go onto the page and under the “domain name” textfield, enter your www subdomain (eg.
www.example.com). Perform the query and wait for a while. If everything works, you will see a list of addresses, similiar to the following list:
<username>.github.io. github.map.fastly.net. prod.github.map.fastlylb.net. 126.96.36.199
If you want a more verbose query with more information you can choose to uncheck the “short” checkbox.
What does the list mean? When you visit
www.example.com, it resolves to
<username>.github.io. That is what the first line represent. So the list is basically a “path” of what the request went through, finally arriving at GitHub Page’s IP address:
Try this instead
What about apex domain? Didn’t you mention it before? What about the
A record that you mention earlier?
Run the verbose DIG query (without the “short” selected) on your domain. If everything is working well, you will notice the last line of the records (the end of the “path”) is actually an
What this actually means is that when everything is finally resolved, the final IP address that your
www.example.com points to is that
What if you want your
example.com to point to an IP address too? What if you want to setup your github pages with an apex domain?
Changes these settings
First go over to GoDaddy DNS management portal. Add 2
A entries into the table. Link them to
188.8.131.52 respectively. These are the IP addresses for GitHub Pages server. Your table will now look something like this:
Name/Host Type Value @ A 184.108.40.206 @ A 220.127.116.11
@ symbol represent the apex domain (eg. example.com), without any subdomain. The following setting will redirect the apex domain (
example.com) to your GitHub Page.
If you want to resolve a subdomain to your GitHub page, you can do so by changing the “Name/Host” to whatever subdomain you want. (changing it to
blog will result in
blog.example.com resolving to your GitHub page.
If you need help, you can refer to the official help page.
Checking that it works
Use the DIG tool that I told you just down. Query your own domain, you should see a list like this:
These IP addresses represent the
A records that your domain has been pointed to.
There are many different kind of records that DNS server use to help resolve different requests. This posts only cover a few of those. If you want to learn more you can take a look here to see what’s the difference between the varying types of records.
A records, but other hosting platforms might use different kinds of DNS records such as
ANAME. To learn more about setting up GitHub Pages on those hosting sites, you can take a look at GitHub’s own help page.