The repository name for your GitHub Pages site must be 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


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

A@ min
A@ min
A@ min
A@ min

The CNAME record

CNAMEwwwyouracct.github.io15 min

The (Optional) AAAA records

AAAA@2606:50c0:8000::15315 min
AAAA@2606:50c0:8001::15315 min
AAAA@2606:50c0:8002::15315 min
AAAA@2606:50c0:8003::15315 min

Verifying the record changes

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

$ dig +noall +answer +nocmd   900     IN      CNAME 506     IN      A 506     IN      A 506     IN      A 506     IN      A

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

$ dig +noall +answer +nocmd       900     IN      A       900     IN      A       900     IN      A       900     IN      A

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

$ dig +noall +answer +nocmd AAAA       900     IN      AAAA    2606:50c0:8003::153       900     IN      AAAA    2606:50c0:8000::153       900     IN      AAAA    2606:50c0:8001::153       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 repo
  2. Go to Settings -> Pages
  3. Enter your custom domain, e.g., in the Custom Domain field
    • Do not use
  4. Check the “Enforce HTTPS” box - SSL certificates will be generated for you

If you are renaming a repository, or deleting 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 and find that it is loading a blank white page. This can happen if your root isn’t but is instead something like 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
  • 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 = ""
languageCode = "en-us"
title = "My Example Blog"

  # 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. instead of

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


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

Cover photo by Annie Spratt on Unsplash