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 TXTThe 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.
Related pages
- How to point a domain at your app, with one record for every subdomain
- How to deploy your app on every push
- The cloud, for AI apps
See also
Glossary terms used on this page: Provider, Workflow.
Sources
All checked on 2026-11-16.
- GitHub, Managing a custom domain for your GitHub Pages site; Verifying a custom domain for GitHub Pages; About custom domains and GitHub Pages; Securing your GitHub Pages site with HTTPS
- IETF, RFC 1034, Domain names — concepts and facilities
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.