A GitHub Pages project gets a URL like USERNAME.github.io/project-name, which is fine until you want to hand it to someone. A subdomain fixes that. I'll use gallery.example.com throughout; swap in your own.
This assumes the project publishes from a branch and Cloudflare runs your DNS. Nothing here takes the default github.io URL down, so you can poke at it while the new name propagates.
Step zero: verify the domain
Before touching the repository, verify the domain in your GitHub account or organization settings. GitHub hands you a TXT record to add. Once verification passes, leave the TXT record where it is. It's tempting to clean it up. Don't.
Then claim it in the repo
In the repository, go to Settings > Pages, enter gallery.example.com under Custom domain, and save.
The order is the part people get wrong. GitHub wants the repository to claim the domain before any DNS points at GitHub, because a record pointing at GitHub with nobody claiming it is an invitation for someone else's repo to take it over. So: repo setting first, DNS second.
For branch publishing, saving that setting makes GitHub commit an uppercase CNAME file to the root of your publishing source. Its entire contents:
gallery.example.com
This tiny file is the thing that bites. If your build wipes and regenerates the publishing directory, it can take CNAME with it, and the custom domain silently stops working on the next deploy. Make sure your build preserves it.
If you deploy with a custom GitHub Actions workflow instead, none of this applies. GitHub ignores CNAME in that mode and doesn't need it.
The Cloudflare record
One record in the Cloudflare DNS zone:
| Type | Name | Target | Proxy status |
|---|---|---|---|
| CNAME | gallery | USERNAME.github.io | DNS only |
USERNAME is the GitHub account or organization name. The repository name does not go in the target. A project living at USERNAME.github.io/project-name still points at plain USERNAME.github.io. GitHub works out the rest from the custom domain you set in the repo.
I keep it DNS-only (grey cloud) during setup. GitHub's docs describe validating a CNAME, and a proxied record makes Cloudflare answer with its own addresses instead. Cloudflare has general advice about proxying web-serving CNAMEs, but nothing specific to GitHub Pages, so I'd rather not guess.
If you do flip the proxy on later, every request starts going through Cloudflare first. That orange cloud looks like a toggle and behaves like a new hop in your request path, so re-test certificate renewal, redirects, and caching afterwards.
Check the record
Before changing anything else, ask DNS what it thinks:
dig gallery.example.com +noall +answer -t CNAME
You want gallery.example.com coming back as a CNAME for USERNAME.github.io.
Propagation can take up to 24 hours. The wrong move during that window is to start editing records on a hunch. If GitHub can't validate the domain, run dig again and look at what's actually there.
HTTPS
Once GitHub validates the domain, go back to Settings > Pages and tick Enforce HTTPS. That checkbox can itself take up to 24 hours to become clickable, because GitHub has to issue the certificate first.
Don't add an HTTPS redirect rule on the Cloudflare side until the GitHub Pages certificate is live. Redirecting to an HTTPS endpoint that has no certificate yet gets you nowhere.
No wildcards
Don't use a wildcard record like *.example.com for this. GitHub explicitly warns that wildcards leave unclaimed subdomains open to takeover, which is the same problem the setup order above exists to avoid.
After every deploy
Configuration drift here is quiet, so I check four things after a deploy. The custom domain should still be set in Settings > Pages. For branch publishing, CNAME should still be sitting in the publishing source. The DNS target should still be USERNAME.github.io. And HTTPS should be enforced before anything starts depending on HTTPS-only asset URLs.