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

The reason why I chose Github Pages is because of my extensive usuage of Github in general for project hosting. Using GitHub Pages fits into my workflow. Have the content ready, push it to GitHub, and it will be deployed to GitHub Pages.

Plus, using GitHub Pages means that you can take advantage of the Jekyll generator. You can focus on your content, push it to GitHub, and it will be “compiled” automatically.

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: .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.

Create a new repository, then go on to the “settings” tabs of your repository.

Note: Your new repository must have the following name: [username].github.io, where [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 test.com, example.com, google.com. These are one level below the top-level domain (.com, .org, etc).

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 blog.test.com, 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 Record

An 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 ..

CNAME Record

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 http://www.example.com, it will be resolved to example.com.

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 http://www.example.com.

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 MX and 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. http://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.
151.101.100.133

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 http://www.example.com, it resolves to .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: 151.101.100.133.

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 A record.

What this actually means is that when everything is finally resolved, the final IP address that your http://www.example.com points to is that 151.101.100.133.

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 192.30.252.153 and 192.30.252.154 respectively. These are the IP addresses for GitHub Pages server. Your table will now look something like this:

Name/Host   Type    Value
@           A       192.30.252.153
@           A       192.30.252.154

The @ 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:

192.30.252.153
192.30.252.154

These IP addresses represent the A records that your domain has been pointed to.

Done?

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.

GoDaddy uses A records, but other hosting platforms might use different kinds of DNS records such as ALIAS or ANAME. To learn more about setting up GitHub Pages on those hosting sites, you can take a look at GitHub’s own help page.