How to Use a Custom Domain for GitHub Pages

3/1/2021

The following is an opinionated “How To” on setting up a custom domain for your GitHub Pages site.

How To

1. Create and publish your CNAME file

Create and publish a CNAME file (no file extension) to the top level / root of your GitHub repo. The only contents of the CNAME file should be the domain that you want to use for your GitHub Pages site. This should be a domain that you own / control! Note, no http:// or https:// is required in the domain.

Example:

www.example.com

The real CNAME for this site:

www.seanosier.com

I recommend using a www. domain, but this is not strictly required.

2. GitHub Pages Setup

Go to your GitHub repo’s “Settings” tab / page:

Scroll down to the “GitHub Pages” section, and set it up to your liking:

• To more fully control what is and is not public, I like to use a Private repo for my GitHub Pages sites.
  

• Source: GitHub provides a few different options for where in your repo GitHub Pages will look for your site. Choose whichever option works best for you. To have more control over what is and is not public, I typically use the /docs folder on the repo’s master branch. (If it’s in /docs, it’s public; if not, it’s not.)
  

• Theme Chooser: GitHub provides a few built-in Jekyll themes that you can use. I normally manage styling / themes outside of GitHub, so I skip this section.
  

• Custom domain: If you already created your CNAME file as shown above, this section should be filled out for you already. If not, you would put the custom domain you want to use here, and GitHub will make the CNAME file for you.
  

• Enforce HTTPS: We’ll come back to this later.

This site’s GitHub Pages setup:

3. DNS Settings

Next, go to the DNS settings wherever your custom domain is registered.

Here’s an example of where this is on Google Domains (the domain registrar for this site):

Update the DNS CNAME and A records as follows:

CNAME Record

Example CNAME record:

your_github_username.github.io

CNAME record for this site:

sosier.github.io

A Record

Example A record (identical to the A record for this site):

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

The CNAME record will handle the www. version of your domain (e.g. www.example.com). The A record will handle the domain without the www. prefix (e.g. example.com).

Final DNS for this site:

(Note, Google Domains DNS likes to put the . on the end of sosier.github.io. This may or may not be the case for your domain registrar.)

4. Verify!

In the command line, use the following commands to verify the DNS update worked.

Checking the CNAME record:

dig www.example.com +nostats +nocomments +nocmd

Real example for this site:

dig www.seanosier.com +nostats +nocomments +nocmd

Expected output for this site:

;www.seanosier.com.		IN	A
www.seanosier.com.	3600	IN	CNAME	sosier.github.io.
sosier.github.io.	3599	IN	A	185.199.111.153
sosier.github.io.	3599	IN	A	185.199.110.153
sosier.github.io.	3599	IN	A	185.199.109.153
sosier.github.io.	3599	IN	A	185.199.108.153

Checking the A record:

dig example.com +noall +answer

Real example for this site:

dig seanosier.com +noall +answer

Expected output for this site:

seanosier.com.		295	IN	A	185.199.108.153
seanosier.com.		295	IN	A	185.199.109.153
seanosier.com.		295	IN	A	185.199.111.153
seanosier.com.		295	IN	A	185.199.110.153

Note, it may take a long time for the change to propagate and take effect. For this site, it took about an hour.

Once that’s working, the final test is to actually visit your site using the custom domain you set up!

5. Setting up HTTPS

Finally, I recommend enforcing HTTPS.

As we saw earlier, this is the final part of the “GitHub Pages” section of the “Settings” tab / page of your repo. To do this, just check the box and you’re done.

Note, GitHub may not allow you to do this immediately. If so, you’ll need to try again later.

Tested On

• Hardware: Lenovo Ideapad 330 15”
  • RAM: 16 GB DDR4 2400MHz
  • Processor: 8th Generation Intel® Core™ i7-8750H Processor (2.20GHz, up to 4.10GHz with Turbo Boost, 9MB Cache)
  • GPU: NVIDIA GeForce GTX 1050 2GB
  • Hard Drive: 128GB Solid State Drive PCIe + 1TB 5400 RPM
• OS: Linux Mint 20 Cinnamon v4.6.7
• Browser: Google Chrome v87.0.4280.141
• GitHub: GitHub Pro (standard GitHub; NOT Enterprise hosted)
• Domain Registrar: Google Domains

Sources

1. https://docs.github.com/en/github/working-with-github-pages/about-custom-domains-and-github-pages
2. https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site

Like This?

Subscribe for More in the Future

Contact Me with Comments / Questions / Suggestions