Custom domain for Netlify

Last updated: September 25, 2026

Netlify serves your site on <site>.netlify.app. A free OpenRepos subdomain gives it a stable address; Netlify issues the certificate after the DNS is verified.

Before you start

  • A Netlify site that already deploys (the free plan is enough).
  • A public GitHub repository with a LICENSE — OpenRepos serves open source projects only.
  • 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": "awesome-project.netlify.app"
  }
}

Use your site's production hostname (<site>.netlify.app) as the target. If Netlify asks you to verify with a netlify-challenge record, include it in the claim:

"txt": {
  "name": "netlify-challenge",
  "value": "<the value you choose and enter in Netlify>"
}

2. Add the domain in Netlify

Open your site's Domain management, choose Add a domain → Add a domain you already own, enter your OpenRepos subdomain (for example awesome-project.openrepos.org) and confirm.

Netlify checks the CNAME that OpenRepos already created. Its instructions may show a CNAME to <site>.netlify.app — you do not need to add it yourself.

If Netlify asks for verification, it points at netlify-challenge.awesome-project.openrepos.org: add the txt field with the same value you entered in Netlify, and DNS sync creates the record.

3. Provision HTTPS

Open Domain management → HTTPS, choose Verify DNS configuration, then let Netlify provision the Let's Encrypt certificate. The padlock usually appears within minutes of verification.

Troubleshooting

  • "Pending DNS verification" — open the domain panel in Netlify for the exact expected record; with OpenRepos the CNAME exists, so this usually clears after the claim is merged and DNS propagates.
  • "DNS verification failed" — check dig awesome-project.openrepos.org CNAME; it should return <site>.netlify.app. If you changed the target, update register.json.
  • Certificate stays pending — verify the DNS configuration in the HTTPS panel first; Netlify will not issue a certificate before that check passes.
  • The subdomain shows the OpenRepos page — the claim is not merged yet; explicit CNAMEs take precedence over the wildcard redirect once they exist.

Frequently asked questions

Why does Netlify ask for a netlify-challenge TXT record?

Netlify requires verification before attaching a subdomain that could collide with a domain on another Netlify account. Add a TXT record at netlify-challenge.<your-subdomain> and enter the same value in Netlify when prompted.

Which target should I use?

Your site's production hostname, <site>.netlify.app, is allowlisted and the simplest choice.

Who issues the certificate?

Netlify does, automatically, after the DNS is verified. Check Domain management → HTTPS → Verify DNS configuration, then Netlify provisions the Let's Encrypt certificate.

My domain shows "Pending DNS verification" — what now?

Open the domain's panel in Netlify; it shows the exact record it expects. With OpenRepos the CNAME is already in place, so this usually clears within minutes after the claim is merged.

Next steps

See all guides for other providers, or compare free subdomain services. Stuck? Open an issue in the register repository.