How to use a custom domain with GitHub Pages

About the DNS configuration of a typical GitHub Pages site

Posted by Anna Monus on September 27, 2018

If you have a custom domain you can quickly set it up with your Jekyll site hosted on GitHub Pages. By default, GitHub Pages sites come with domains ending in github.io. To use it with a custom domain, you only need to configure your DNS settings.

The big thing about GitHub Pages is that GitHub lets you host your static website on its servers for free. Besides, since May 2018, it even offers free HTTPS support for custom domains.

I will discuss the most typical use case when you want to point both the apex domain and the www subdomain to GitHub Pages. The apex domain is the (non-www) root domain without a subdomain, for instance, annalytic.com for me. There are other, more complicated use cases as well—GitHub Docs detail all of them comprehensively.

There are two places where you need to configure your DNS settings:

  1. at your domain provider
  2. in your GitHub repo

1. DNS management in your GitHub account

Go to the Settings page of the GitHub repo of your site and enter your custom domain into the "GitHub Pages" section.

GitHub Pages custom domain settings

This setting automatically creates a CNAME record in the root folder of your repo. CNAME stands for Canonical Name and DNS servers use it to alias one domain name to another. You can also make GitHub use HTTPS with your custom domain by ticking the "Enforce HTTPS" checkbox.

2. DNS management at your DNS provider

Log in to your account at your domain provider and navigate to the "DNS Management" (or similarly named) section inside the admin area. Here, you need to do two things:

  1. Create A records that point your apex domain to GitHub Pages' servers. You need to create four A records.
  2. Create a CNAME record that points the www subdomain to your default GitHub Pages site.

Here are the five DNS records you need to set up:


Host Name       Record Type         Address
@               A (Address)         185.199.108.153
@               A (Address)         185.199.109.153
@               A (Address)         185.199.110.153
@               A (Address)         185.199.111.153
www             CNAME (Alias)       yoursite.github.io

If you get stuck somewhere have a look at the detailed documentation about how to set up GitHub Pages with a custom apex domain and a www subdomain.

Check if everything's all right

You usually have to wait up to 24 hours until the changes propagate. Then, you can check the health of your DNS servers by running a free DNS test with a provider such as Leaf DNS. You should see something like this:

Leaf DNS test for GitHub Pages

GitHub also shows a warning if there are any problems with your configuration. That's all.