Deploying to GitHub Pages with a Custom Domain

I deployed this site to GitHub Pages and wanted to use a custom domain. This post documents the configuration that worked.

Repo: https://github.com/mohammedhammoud/mohammedhammoud.com

Checklist

To serve a custom domain from GitHub Pages, all of this must be true:

DNS matches GitHub’s documented records (https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https#verifying-the-dns-configuration)
GitHub Pages is enabled for the repository
A successful Pages deploy has run at least once
The custom domain is saved in GitHub so validation and TLS can start
A CNAME file exists in the published Pages output

If one of these is missing, you may see:

NotServedByPagesError

GitHub configuration

1. Enable Pages

Open:

Settings
Pages

Under Build and deployment:

Source: GitHub Actions

Without an active Pages deployment, GitHub cannot validate or serve your custom domain.

2. Save your custom domain

Still on the Pages settings page, set:

Custom domain: mohammedhammoud.com

Save it.

After saving, GitHub should start:

DNS validation
TLS certificate provisioning

Wait for TLS provisioning, then enable Enforce HTTPS.

If the domain is attached to another Pages site, you must remove it there first.

DNS configuration in your domain registrar

In your domain registrar (I use Loopia):

1. Remove wildcard records

Remove any wildcard * records.

2. Point `www` to GitHub Pages

Set www as a CNAME to your GitHub Pages host:

CNAME  www  mohammedhammoud.github.io.

3. Point the apex domain to GitHub Pages

Use the A records documented by GitHub (in case they change over time):

https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https#verifying-the-dns-configuration

4. Leave mail DNS alone

If you use email on the domain, do not touch mail-related records such as MX, SPF, autodiscover, and similar.

What I actually did in my registrar

Removed wildcard * A-records that pointed to a Loopia IP (so unknown subdomains no longer resolved incorrectly).
Set the apex @ to GitHub Pages using these A-records:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Set www as a CNAME to:

mohammedhammoud.github.io.

Left mail DNS unchanged (MX/SPF/etc).
Verified DNS externally (not just locally) with:

dig @1.1.1.1 +short A mohammedhammoud.com
dig @8.8.8.8 +short A mohammedhammoud.com
dig @1.1.1.1 +short CNAME www.mohammedhammoud.com
dig @8.8.8.8 +short CNAME www.mohammedhammoud.com

…and confirmed that dig +short A test123.mohammedhammoud.com returned empty (wildcard removed).

Verify DNS globally

Run these checks against a public resolver:

dig @1.1.1.1 +short A mohammedhammoud.com
dig @1.1.1.1 +short CNAME www.mohammedhammoud.com

If DNS is correct but GitHub still complains, the usual causes are:

Pages is not enabled, or not set to GitHub Actions
The repo has not deployed a Pages site yet
The domain is attached to a different Pages site

Result

After DNS validation and TLS provisioning complete:

https://www.mohammedhammoud.com should load your site
GitHub Pages should allow Enforce HTTPS

Mohammed Hammoud