How to Use a Custom Domain With GitHub Pages

Point your apex domain at GitHub's four documented A records (and, optionally, its AAAA records for IPv6), point www at your username.github.io address with a CNAME, and add a CNAME file to your repository — that's the whole DNS side of it. GitHub Pages is free static hosting tied to a GitHub repository, and its custom-domain setup is entirely documented at docs.github.com. This covers the apex vs www setup with GitHub's exact record values, domain verification, HTTPS enforcement, and the errors that come up most.

What DNS records does GitHub Pages actually need?

It depends on whether you're pointing your root domain (example.com) or a subdomain like www.example.com.

For an apex domain, GitHub documents four A records, all pointed at these addresses: 185.199.108.153, 185.199.109.153, 185.199.110.153, and 185.199.111.153 (GitHub Docs, "Managing a custom domain for your GitHub Pages site", checked September 2026). If your DNS provider supports IPv6, GitHub also documents four matching AAAA records: 2606:50c0:8000::153, 2606:50c0:8001::153, 2606:50c0:8002::153, and 2606:50c0:8003::153 (same source).

For a www subdomain, the record is a single CNAME that points www.example.com to <user>.github.io or <organization>.github.io — your GitHub Pages address, not a raw IP (same source).

Most setups use both together: A (and optionally AAAA) records at the apex, plus a CNAME at www redirecting to whichever one you set as primary in your repository settings. Our guide to CNAME vs A records covers why this apex/www split exists in DNS generally, and it's the same underlying rule here — a CNAME can't share the apex with the other records already required there.

What has to be set inside the repository, not just DNS?

Alongside the DNS records, GitHub Pages needs a file named CNAME (all uppercase) at the root of your repository, containing your domain name. GitHub's documentation is specific about the constraints on that file: "The CNAME filename must be all uppercase. The CNAME file can contain only one domain" (GitHub Docs, "Troubleshooting custom domains and GitHub Pages", checked September 2026). If you're using a static site generator, that same page flags a common failure mode: the generator can silently overwrite or drop that file during its own build, so GitHub recommends confirming the CNAME commit is actually present before you rely on the build having kept it.

Should I verify my custom domain?

GitHub recommends it, and treats it as a security step rather than an optional extra. Its documentation states: "You can increase the security of your custom domain and avoid takeover attacks by verifying your domain" (GitHub Docs, "Verifying your custom domain for GitHub Pages", checked September 2026). The risk it addresses is specific: "Domain takeovers can happen when you delete your repository, when your billing plan is downgraded, or after any other change which unlinks the custom domain" (same source) — if your DNS still points at GitHub Pages but nothing on GitHub's side claims the domain anymore, someone else could potentially claim it.

Verification works by adding a DNS TXT record in the pattern _github-pages-challenge-USERNAME.example.com (for a personal account) or the organization equivalent, with a value GitHub gives you when you start the process (same source). GitHub's own instructions on the setup page tell you to "Follow the instructions under 'Add a DNS TXT record' to create the TXT record with your domain hosting service," wait for DNS propagation (up to 24 hours), confirm it with a dig lookup, and then click Verify. Keep the TXT record in place afterward — removing it can undo the verified status.

How do I set this up, step by step?

1. Add the four A records (and AAAA records, if supported) at your DNS host, using the exact values GitHub documents above, for your apex domain.
2. Add a CNAME record for www, pointed at your <user>.github.io or <organization>.github.io address, if you want the www version to work too.
3. Verify your domain, per the process above, before or shortly after adding it to your repository — GitHub recommends doing this first.
4. Add the domain in your repository's Pages settings, which creates or updates the CNAME file in your repository automatically.
5. Choose which version is primary. GitHub's Pages settings let you set either the apex or the www version as primary, and it will redirect the other to it — decide before launch, since this affects which URL search engines and links should treat as canonical.
6. Wait for DNS to propagate, then confirm the site loads on the custom domain in a browser.
7. Enable HTTPS. In Pages settings, select Enforce HTTPS. GitHub's documentation notes: "It can take up to 24 hours before this option is available" (GitHub Docs, "Managing a custom domain...") after the domain is added, and separately, the troubleshooting page notes "it can take up to an hour for your site to become available over HTTPS after you configure your custom domain."

What are the common errors, and how do I fix them?

GitHub's troubleshooting documentation names several specific, recurring problems:

• A CNAME file with more than one domain, or lowercase filename. Fix: the file must be named exactly CNAME, in all capitals, and contain only the single domain you're using.
• Multiple domains competing for the same slot. GitHub's troubleshooting page says a site must not use more than one apex domain, more than one www subdomain, or both an apex domain and a custom subdomain other than www (GitHub Docs) — pick one apex and, optionally, one www alias, not several of either.
• A wildcard DNS record on the domain. GitHub "strongly recommend[s] that you do not use wildcard DNS records, such as *.example.com," specifically because of the same domain-takeover risk verification is meant to prevent.
• HTTPS not activating. If Enforce HTTPS doesn't become available or doesn't work after the documented delay, GitHub's troubleshooting page's suggested fixes include removing and re-adding the custom domain to re-trigger HTTPS provisioning, and confirming your domain's CAA records (if you have any) include letsencrypt.org — a CAA record that excludes GitHub's certificate authority will block certificate issuance regardless of anything else being correct.
• A change that doesn't seem to take effect. Before assuming something is broken, GitHub's own advice is to check the DNS directly, with a command such as dig or any public DNS lookup tool, rather than trusting what your local browser cache still shows.

What if I already had a different domain connected?

Removing a custom domain, or letting your Pages site become disabled while a domain still points at it, is exactly the scenario GitHub's own documentation calls a takeover risk. Before changing domains, update or remove the old CNAME file and DNS records together, rather than one and not the other, and re-verify the new domain following the same process. If you're moving the whole site's DNS off GitHub Pages entirely rather than swapping to a different custom domain on GitHub Pages, treat it the same as any other host change: our CNAME vs A record guide covers the general mechanics of pointing a domain somewhere new, including how DNS propagation delay affects the switch either direction.

Bottom line: GitHub Pages' custom-domain setup is fully documented at docs.github.com — four specific A records (plus optional AAAA records) for an apex domain, a CNAME for www, an uppercase single-domain CNAME file in your repository, and a recommended, TXT-record-based verification step to close off the takeover risk GitHub names explicitly. HTTPS activates automatically after a documented delay once the domain and DNS are both correct.