# How to Use a Custom Domain With GitHub Pages

Canonical: https://figment.so/blog/github-pages-custom-domain

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.

**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"](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/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](/blog/cname-vs-a-record) 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"](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/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..."](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site)) 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"](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/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](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages)). 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](/blog/cname-vs-a-record) covers pointing a domain somewhere new and how DNS propagation delay affects the switch.
