Use a subdomain when you need a stable public name for a GitHub Pages project. I use gallery.example.com below as the example. Replace it with your domain.
This guide covers a project that publishes from a branch and uses Cloudflare for DNS. The default GitHub Pages URL remains available during setup.
Verify the domain first
Verify the domain in the GitHub account or organization settings before you configure the repository. GitHub uses a TXT record for this check. Keep the TXT record after verification.
Set the domain in GitHub first
In the repository, open Settings > Pages. Under Custom domain, enter gallery.example.com and save the setting.
The order matters. Set the custom domain in GitHub before you create the DNS record. GitHub recommends this order because DNS that points to GitHub before the repository claims the domain can create a takeover risk.
For branch publishing, GitHub adds an uppercase CNAME file to the root of the publishing source. The file contains only the domain name:
gallery.example.com
Keep the file in the publishing source. A build that replaces the publishing directory can remove it. This is an easy failure to miss.
This rule does not apply to a custom GitHub Actions workflow. In that mode, GitHub ignores CNAME and does not require it.
Add the Cloudflare DNS record
Create this record in the Cloudflare DNS zone:
| Type | Name | Target | Proxy status |
|---|---|---|---|
| CNAME | gallery | USERNAME.github.io | DNS only |
Replace USERNAME with the GitHub account or organization name. Do not add the repository name to the target. For example, a project at USERNAME.github.io/project-name still uses USERNAME.github.io as the CNAME target.
This example keeps the record DNS-only during setup. GitHub documents CNAME validation, while Cloudflare returns its own addresses for proxied records. Cloudflare gives general proxy guidance for web-serving CNAME records, but it does not give GitHub Pages-specific proxy guidance.
Do not treat a proxy change as a DNS toggle. It changes the request path. Test certificate renewal, redirects, and cache behavior after the change.
Verify the record
Check the CNAME record before you change any other setting:
dig gallery.example.com +noall +answer -t CNAME
The response should show gallery.example.com as a CNAME for USERNAME.github.io.
DNS changes can take up to 24 hours. Do not wait and change records at random. Check the record again if GitHub cannot validate the domain.
Enable HTTPS
Return to Settings > Pages after GitHub validates the domain. Enable Enforce HTTPS when the control becomes available.
GitHub can take up to 24 hours to make this control available. Do not add an HTTPS redirect rule until the GitHub Pages certificate is active.
Avoid wildcard DNS records
Do not use a wildcard DNS record such as *.example.com for GitHub Pages. GitHub warns that wildcard records can expose unclaimed subdomains to takeover.
Deployment checks
Use these checks after each deployment. They catch most configuration drift:
- Confirm that the custom domain remains set in Settings > Pages.
- For branch publishing, confirm that the publishing source still contains
CNAME. - Confirm that the CNAME target is
USERNAME.github.io. - Confirm that HTTPS is enabled before you require HTTPS-only asset URLs.