Custom domain for GitHub Pages

Last updated: September 25, 2026

GitHub Pages serves your project on <owner>.github.io, an address shared with every other project in the account. A free OpenRepos subdomain gives your project its own name — GitHub Pages issues the TLS certificate for it.

Before you start

  • A public GitHub repository with a LICENSE — OpenRepos serves open source projects only.
  • GitHub Pages already enabled and serving your site (Settings → Pages shows the site URL).
  • The OpenRepos badge in your README: CI checks it on every new claim.

1. Claim your subdomain

Pick a free name with the domain picker, then add it to register.json under the domain you chose:

"openrepos.org": {
  "awesome-project": {
    "repo": "https://github.com/octocat/awesome-project",
    "target": "octocat.github.io"
  }
}

Use the user or organization site host as the target — <owner>.github.io, not the repository name. Project sites (owner.github.io/repo) use the same target.

Add the badge to your README and open the pull request; CI validates naming, ownership and the badge. After a maintainer merges, the CNAME record is created automatically — usually within a minute.

2. Add the custom domain in GitHub Pages

In the repository, open Settings → Pages → Custom domain, enter your OpenRepos subdomain (for example awesome-project.openrepos.org) and click Save.

GitHub commits a CNAME file to the publishing branch and starts a DNS check. Wait for "DNS check successful" — with OpenRepos DNS this is usually immediate.

If you deploy Pages with a custom GitHub Actions workflow, deployments can overwrite the CNAME file. Set the domain in the workflow instead (the cname input of actions/configure-pages) or make sure the file survives the deployment.

3. Enable Enforce HTTPS

Still under Settings → Pages, tick Enforce HTTPS. GitHub provisions a certificate after the DNS check passes; this usually takes minutes and at most 24 hours.

If the checkbox is greyed out, the certificate is not ready yet: confirm the DNS check succeeded, then reload the settings page. Do not remove and re-add the domain while you wait.

Troubleshooting

  • "Domain is already taken" — a CNAME file with this domain exists in another repository or branch. Remove it there, then save again.
  • 404 after adding the domain — the Pages build failed or the publishing branch has no content; the custom domain only changes the address, not the site.
  • "DNS check unsuccessful" — DNS has not propagated yet (up to 24 hours) or the record points elsewhere. Check with dig awesome-project.openrepos.org CNAME; it should return <owner>.github.io.
  • TLS error or "Not secure" — the certificate has not been issued yet, or the domain was added somewhere else. Wait, then re-check the DNS check result.

Frequently asked questions

Do I still need the CNAME file that GitHub creates?

Yes. The CNAME file tells GitHub Pages which custom domain to serve, and GitHub commits it for you when you save the domain in Settings → Pages. Keep it in the publishing branch.

Will the subdomain replace my owner.github.io URL?

No. Both addresses keep serving the same site; the OpenRepos subdomain is additive. GitHub redirects the github.io address to the custom domain when Enforce HTTPS is on.

Can I use an apex domain with GitHub Pages?

GitHub Pages supports apex domains with A records, but OpenRepos provides subdomains only — so this does not apply to a claimed subdomain.

How long does HTTPS take?

GitHub issues a Let's Encrypt certificate after the DNS check passes, usually within minutes and up to 24 hours. Enforce HTTPS stays greyed out until the certificate is ready.

Next steps

Deploying to Cloudflare Pages instead? Follow the Cloudflare Pages guide. See all guides, or compare free subdomain services. If anything here is unclear, open an issue in the register repository.