What DNS records GitHub Pages needs for a custom domain

For the apex, create all four of GitHub's A records and, optionally, all four AAAA records; for www, a CNAME to ORGANIZATION.github.io; and a TXT record proving you own the domain. The repository must also have the custom domain set in its Pages settings, or the DNS records point at GitHub with nothing there to answer for that name.

For a site served at example.com:

example.com        A       185.199.108.153
                           185.199.109.153
                           185.199.110.153
                           185.199.111.153
example.com        AAAA    2606:50c0:8000::153
                           2606:50c0:8001::153
                           2606:50c0:8002::153
                           2606:50c0:8003::153
www.example.com    CNAME   ORGANIZATION.github.io.

GitHub asks for all four addresses, not one or two: the four A records and four AAAA records are listed as a set in its custom-domain instructions, checked 2026-11-16.

Why the apex uses A records

A CNAME cannot sit at the apex, because the apex already carries NS and SOA records, and a CNAME may not share a node with other data. RFC 1034 says: "If a CNAME RR is present at a node, no other data should be present" (RFC 1034, section 3.6.2, checked 2026-11-16). The apex is exactly such a node, so GitHub publishes A and AAAA addresses for it instead.

Where a DNS provider offers an ALIAS or ANAME record, GitHub also accepts one at the apex pointing to USERNAME.github.io or ORGANIZATION.github.io (same GitHub page). A plain CNAME at the apex is not an option.

www is a CNAME, and GitHub redirects it

Point www at the Pages hostname with a CNAME, not at the repository or at the *.pages.github.io hostname shown in the repository settings. GitHub's instructions name USERNAME.github.io or ORGANIZATION.github.io as the target (custom-domain instructions, checked 2026-11-16).

You can configure the apex, www, or both. When both are configured with the right records, GitHub Pages redirects www.example.com to example.com for an apex custom domain, and its documentation recommends using a www subdomain even when the apex is the canonical name (About custom domains and GitHub Pages, checked 2026-11-16). Without a www record (and with no wildcard), www.example.com does not resolve at all.

Prove you own the domain

Create the TXT record GitHub shows in your account's Pages settings, then keep it there. For an organization site the name is _github-pages-challenge-ORGANIZATION.example.com; for a user site it is _github-pages-challenge-USERNAME.example.com. The value is generated by GitHub, and verification happens in your profile settings or organization settings, not in the repository (Verifying a custom domain for GitHub Pages, checked 2026-11-16).

Verification is what stops someone else claiming the domain after it stops being used by your Pages site — for example after a repository is deleted or a plan is downgraded while the domain is still configured. Keep the TXT record in place to stay verified (same page).

Tell the repository as well

Add the custom domain in the repository's Pages settings before you configure DNS. GitHub recommends that order, and saving the domain is what makes the repository claim it (custom-domain instructions, checked 2026-11-16).

If Pages publishes from a branch, saving the custom domain commits a CNAME file at the root of the source branch. If it publishes from a custom GitHub Actions workflow, no CNAME file is created, and one that is present is ignored (same page). In either case, the domain must be set in the repository settings; DNS alone does not tell GitHub which site answers for the name.

HTTPS follows the DNS check

Once the DNS records are right, GitHub Pages requests a certificate for the custom domain automatically. It queues a Let's Encrypt certificate and uploads it; provisioning can take time, and extra or wrong records can prevent a certificate from being issued (Securing your GitHub Pages site with HTTPS, checked 2026-11-16). The repository can then enforce HTTPS.

GitHub's sample answers use a TTL of 3600 seconds; it does not require a particular value. A shorter TTL makes later address changes take effect sooner.

Check it

for h in example.com www.example.com; do
  printf '%-24s ' "$h"; dig +short "$h" A
done
dig +short example.com AAAA
dig +short www.example.com CNAME
dig +short _github-pages-challenge-ORGANIZATION.example.com TXT

The apex should return all four A addresses, and all four AAAA addresses if you added them. www should return ORGANIZATION.github.io. as its CNAME. The challenge name should return the TXT value GitHub gave you. A name that returns nothing is missing or misspelled in the zone; a name returning an old address is answered from a cache until its TTL expires.

See also

Glossary terms used on this page: Provider, Workflow.

Sources

All checked on 2026-11-16.


First version written with AI assistance and checked against the sources on 2026-11-16. Found a mistake? Fix it or open an issue. Text licensed under CC BY 4.0.