Quick Guide: GitHub Pages with Custom Domain

Prerequisites

The repository name for your GitHub Pages site must be youracct.github.io. This means that you must either:

• Create a new repository with this name OR
• Change an existing repository to this name
  • If changing a repository name, make sure you are aware of any implications to the code and configuration of that repository.

If you have used your desired domain for any other purpose previously, check:

• That the nameservers are the registrar’s nameservers
• That there are no conflicting A, AAAA, or CNAME records in the DNS configuration

~*~*Capitalism*~*~

The repository must be public if you are using a free plan for GitHub. If you are on a paid plan you can use either a public or private repository.

Configure DNS

You don’t necessarily need to do this first; however, doing it first will prevent the checks from failing during set up if you do it second.

You will need to configure:

• 4 A records (IPv4)
• 1 CNAME record
• (Optional) 4 AAAA records (IPv6)

The A records

The CNAME record

The (Optional) AAAA records

Verifying the record changes

Run the following to verify your CNAME record is pointing correctly:

$ dig +noall +answer +nocmd www.example.com
www.example.com.   900     IN      CNAME   youracct.github.io.
youracct.github.io. 506     IN      A       185.199.108.153
youracct.github.io. 506     IN      A       185.199.109.153
youracct.github.io. 506     IN      A       185.199.110.153
youracct.github.io. 506     IN      A       185.199.111.153

Run the following to verify your A records are pointing correctly:

$ dig +noall +answer +nocmd example.com
example.com.       900     IN      A       185.199.110.153
example.com.       900     IN      A       185.199.111.153
example.com.       900     IN      A       185.199.108.153
example.com.       900     IN      A       185.199.109.153

Run the following to verify your (optional) AAAA records are pointing correctly:

$ dig +noall +answer +nocmd example.com AAAA
example.com.       900     IN      AAAA    2606:50c0:8003::153
example.com.       900     IN      AAAA    2606:50c0:8000::153
example.com.       900     IN      AAAA    2606:50c0:8001::153
example.com.       900     IN      AAAA    2606:50c0:8002::153

Quick Troubleshooting

If the above doesn’t propagate correctly in an hour:

1. Check that your desired configuration is correct for all records and nameservers
2. Check that there are no lingering conflicts from prior use of the same domain

If you see different IPs other than the ones that you have configured, you can use an IP lookup tool to see the owner of those IPs. That should point you in the direction of your last use, if you no longer recall / the domain is being managed by another service.

Configure GitHub Pages

1. Navigate to the youracct.github.io repo
2. Go to Settings -> Pages
3. Enter your custom domain, e.g. example.com, in the Custom Domain field
   • Do not use www.example.com
4. Check the “Enforce HTTPS” box - SSL certificates will be generated for you

If you are renaming a repository, or deleting youracct.github.io to create a new repository with the same name, you may need to wait while the necessary changes take effect. For renamed repositories: make sure to handle all other changes that may be required so you don’t run into issues with git and/or your site.

Quick Troubleshooting

A Common Issue: “White page when accessing custom domain”

Basically: after all of the above is done, “green” / passing and correct, you go to example.com and find that it is loading a blank white page. This can happen if your root isn’t example.com but is instead something like example.com/posts. If you are a Hugo user and went through the Hugo Quickstart, this definitely applies to you. There are two ways to resolve this:

• Always link to example.com/posts
• In Hugo’s case, look up the how the theme needs to have the defualt posts made to /. e.g. in config.toml you might see:

baseURL = "https://example.com/"
languageCode = "en-us"
title = "My Example Blog"
theme="hello-friend"

[params]
  # dir name of your blog content (default is `content/posts`).
  # the list of set content will show up on your index page (baseurl).
  contentTypeName = "posts"

The above sets the theme to “Hello Friend"^* and makes posts the root directory for the site, i.e. example.com instead of example.com/posts.

^*The “Hello Friend” theme was deprecated in 2023, though a newer “Hello-Friend-ng” has picked up the torch.

References

GitHub Pages documentation - starting with the Quick Start and going through the Custom Domains.

Cover photo by Annie Spratt on Unsplash