Anna Monus | Technical Writing & Editing

How to use a custom domain on GitHub Pages

DNS configuration of a GitHub-hosted Jekyll site

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 To use your GitHub-hosted site with your custom domain, you only need to configure your DNS (Domain Name System) settings. Then, you can quickly check if your new domain properly works with the help of a DNS-testing service such as LeafDNS.

GitHub lets you host your static website on its servers for free. Since May 2018, it also 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, 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)
@ A (Address)
@ A (Address)
@ A (Address)
www CNAME (Alias)

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 Leaf DNS or a similar provider. 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.