# GitHub Pages domain verification GitHub Pages domain verification helps prevent a GitHub Pages custom-domain takeover. > [!note] This is not a DNS takeover > You still own and control your DNS zone. The risk is that DNS continues pointing at GitHub Pages after your own GitHub Pages site is no longer claiming that hostname. ## Normal mapping Today, to map a custom domain such as `docs.example.com` to a GitHub Pages site such as `owner/project`, you typically need two things: 1. A DNS record that sends the hostname to GitHub Pages, for example: ```text docs.example.com CNAME owner.github.io ``` 2. A custom-domain setting in the GitHub Pages repository that claims `docs.example.com` for that site. When both are present, requests for `docs.example.com` reach GitHub Pages and GitHub knows which repository should serve the content. ## How the mapping becomes orphaned The problem starts when the DNS record remains active but the GitHub-side claim disappears. That can happen if: - Pages is disabled. - The custom domain is removed from the repository. - The repository is deleted. - The repository is renamed in a way that unlinks or breaks the Pages configuration. A rename matters because GitHub Pages routing is tied to repository and Pages configuration state. After a rename or other repository change, the custom domain may no longer be attached to the site that originally claimed it. At that point, DNS still says: ```text docs.example.com -> GitHub Pages ``` But GitHub Pages no longer has your repository claiming `docs.example.com`. ## What an attacker can do If the domain is not verified, another GitHub user may be able to add `docs.example.com` as the custom domain for their own Pages site. Since the DNS record still points to GitHub Pages, traffic for your hostname can then be served by their repository. They have taken over the GitHub Pages mapping for your domain, even though they have not taken over your DNS. ```text Browser request -> docs.example.com -> DNS still points to GitHub Pages -> GitHub Pages serves whichever repository is allowed to claim docs.example.com ``` ## How verification helps Domain verification closes the gap. Verifying the parent domain tells GitHub that **only repositories owned by the verified account or organization** can publish Pages sites for that domain and its immediate subdomains. ## What to verify Verify apex domains that have GitHub Pages records, for example: - `example.com` - `example.org` Verifying `example.com` protects immediate subdomains such as `docs.example.com`, but not deeper names like `v1.docs.example.com`. Avoid wildcard DNS records such as `*.example.com` for GitHub Pages. GitHub warns that wildcard records can leave deeper names exposed to takeover risk even when the apex domain is verified. ## How to verify 1. Go to GitHub account or organization settings. Not your repository settings. 2. Open **Pages**. 3. Add the apex domain, such as `example.com`. 4. GitHub will provide a TXT record name like: ```text _github-pages-challenge-OWNER.example.com ``` 5. Add that TXT record in DNS with the token GitHub provides. 6. Wait for DNS propagation. GitHub says this may be immediate or take up to 24 hours. 7. Click **Verify** in GitHub. 8. Keep the TXT record in DNS so the domain remains verified. GitHub's verification flow shows the DNS TXT record that needs to be added:  ## Official references - [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) - GitHub's official instructions for domain verification, TXT challenge records, takeover protection, wildcard DNS warnings, and keeping the TXT record in DNS. - [About custom domains and GitHub Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages) - GitHub's overview of supported custom domains, DNS record types, and takeover risk when a Pages site is disabled while DNS remains pointed at GitHub Pages.