Every once in a while I need to modify my custom domain’s DNS records to work with GitHub pages, and every time it’s a struggle to get it right. Here I document my currently-working setup.
I followed the recommended setup1 by configuring www as my Custom Domain, also configuring my apex domain, and letting GitHub Pages “automatically create redirects between the domains”. Specifically for this website, I told GitHub that my Custom Domain is www.charlesjlee.com and I setup the DNS records for charlesjlee.com. This involved making changes in three places: DNS records, repo config, site config.
DNS records
My DNS provider is GoDaddy. I added the below five entries to my DNS Records table. The first four A records map the current domain (charlesjlee.com) to the IP addresses for GitHub Pages. The last CNAME record maps the www subdomain (www.charlesjlee.com) to the current domain (charlesjlee.com) so that the www subdomain (www.charlesjlee.com) also points to GitHub Pages’ IP addresses.
| Type | Name | Value | TTL |
|---|---|---|---|
| A | @ | 185.199.108.153 | 1 hour |
| A | @ | 185.199.109.153 | 1 hour |
| A | @ | 185.199.110.153 | 1 hour |
| A | @ | 185.199.111.153 | 1 hour |
| CNAME | www | @ | 1 hour |
After these records are added, you can confirm that DNS is resolving correctly by using nslookup for Windows or dig for Linux. While DNS changes can take a long time (24-72 hours) to propagate worldwide, in my experience, I saw changes appear within minutes.
PS C:\Hugo\charlesjlee-website> nslookup charlesjlee.com Server: UnKnown
Address: 192.168.1.1
Non-authoritative answer:
Name: charlesjlee.com
Addresses: 185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
PS C:\Hugo\charlesjlee-website> nslookup www.charlesjlee.com Server: UnKnown
Address: 192.168.1.1
Non-authoritative answer:
Name: charlesjlee.com
Addresses: 185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
Aliases: www.charlesjlee.com
Repo config
On GitHub, navigate to the Settings tab for your repo and scroll all the way to the bottom to see the GitHub Pages section. Here, you want to:
- Set Source to the correct branch
- Set Custom domain as the www subdomain
- Optionally enable HTTPS
If the DNS records and repo config are correct, you will see a green bar, otherwise, you will see a yellow bar.
Site config
Finally, you’ll want to add or update the CNAME file in your gh-pages branch (or whichever branch you specified above) to be the www subdomain (www.charlesjlee.com).
If you’re generating the CNAME file, e.g. by using GitHub Actions, don’t forget to update your workflow script.
If you enabled HTTPS earlier, make sure your files internally refer to HTTPS or the apex URL to avoid serving mixed content. If you’re using Hugo, this could mean updating BaseURL in config.toml.