Skip to content

Website guide

How to Use a Custom Domain With GitHub Pages

Point your apex domain at GitHub's four A records, point www at your username.github.io address with a CNAME, and add the domain in your repository's Pages settings. Verify the domain, then enforce HTTPS.

Figment editorial teamPublished Updated

To use a custom domain on GitHub Pages, point your apex domain at GitHub's four documented A records (and, if your DNS host supports IPv6, its four AAAA records), point www at your username.github.io address with a CNAME, and add the domain in your repository's Pages settings. GitHub Pages is free static hosting tied to a GitHub repository, and every step below comes from GitHub's own documentation at docs.github.com.

What DNS records does GitHub Pages need?

For an apex domain such as example.com, GitHub documents four A records. For a subdomain such as www.example.com, it documents one CNAME record. Most sites use both: the A records at the apex, plus a CNAME at www.

Apex domain. Create four A records pointing at 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"). 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 page).

www subdomain. Create one CNAME record that points www.example.com to <user>.github.io or <organization>.github.io. That is your GitHub Pages address, not a raw IP (same page).

A CNAME cannot share a name with the other records an apex domain needs, which is why the apex uses A records and www uses a CNAME. Our guide to CNAME vs A records explains the rule.

What does the repository need besides DNS?

The repository needs a file named CNAME (all uppercase) at its root, containing your domain name. GitHub's troubleshooting page sets the constraints: "The CNAME filename must be all uppercase. The CNAME file can contain only one domain" (GitHub Docs, "Troubleshooting custom domains and GitHub Pages").

If you build with a static site generator, the same page flags a common failure: the generator can overwrite or drop that file during its own build. Confirm the CNAME file is present in the published branch before you rely on it.

How do I set up a custom domain on GitHub Pages, step by step?

  1. Add the four A records (and the AAAA records, if supported) for your apex domain at your DNS host, using the values above.
  2. Add a CNAME record for www pointing at your <user>.github.io or <organization>.github.io address, if you want www to work too.
  3. Verify your domain (see the next section). GitHub recommends doing this before or shortly after adding the domain to your repository.
  4. Add the domain in your repository's Pages settings. This creates or updates the CNAME file in your repository.
  5. Choose the primary version. The Pages settings let you set the apex or the www version as primary, and GitHub redirects the other to it. Decide before launch, because it sets which URL search engines and links treat as canonical.
  6. Wait for DNS to propagate, then confirm the site loads on your domain.
  7. Select Enforce HTTPS in Pages settings. GitHub notes: "It can take up to 24 hours before this option is available" (GitHub Docs, "Managing a custom domain...") after you add the domain. The troubleshooting page adds that "it can take up to an hour for your site to become available over HTTPS after you configure your custom domain."

Should I verify my custom domain?

Yes. GitHub treats verification as a security step: "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"). The risk 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 page). If your DNS still points at GitHub Pages but nothing on GitHub's side claims the domain, someone else could claim it.

To verify, add a DNS TXT record named _github-pages-challenge-USERNAME.example.com (for a personal account) or the organization equivalent, with the value GitHub gives you when you start. GitHub tells you to "Follow the instructions under 'Add a DNS TXT record' to create the TXT record with your domain hosting service." Then wait for DNS propagation (up to 24 hours), confirm the record with a dig lookup, and click Verify. Keep the TXT record in place afterward, because removing it can undo the verified status.

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

GitHub's troubleshooting documentation names these recurring problems:

  • A CNAME file with a lowercase name or more than one domain. Name the file exactly CNAME and put only the single domain you use in it.
  • Several domains competing for the same slot. 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.
  • A wildcard DNS record. GitHub "strongly recommend[s] that you do not use wildcard DNS records, such as *.example.com," because of the same takeover risk that verification addresses.
  • HTTPS not activating. If Enforce HTTPS does not become available after the documented delay, GitHub suggests removing and re-adding the custom domain to restart HTTPS provisioning. Also check your CAA records, if you have any. They must include letsencrypt.org, or certificate issuance is blocked.
  • A change that does not seem to take effect. Check DNS directly with dig or a public DNS lookup tool, not with what your local browser cache still shows.

What if a different domain was already connected?

Update or remove the old CNAME file and the old DNS records together, not one without the other, and re-verify the new domain with the same process. Removing a custom domain, or letting your Pages site become disabled while a domain still points at it, is the scenario GitHub calls a takeover risk.

If you are moving the whole site's DNS off GitHub Pages rather than swapping domains, treat it like any other host change. Our CNAME vs A record guide covers pointing a domain somewhere new and how DNS propagation delay affects the switch.