Custom domain for GitLab Pages

Last updated: September 25, 2026

GitLab Pages serves your project on <namespace>.gitlab.io and requires two DNS records for a custom domain: a CNAME and a verification TXT record. A free OpenRepos subdomain supports both — the claim creates them automatically.

Before you start

  • A GitLab project with Pages enabled and a successful Pages deployment (GitLab.com or a self-managed instance with Pages).
  • 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. Create the domain in GitLab Pages

In your GitLab project open Deploy → Pages → New Domain, enter your OpenRepos subdomain (for example awesome-project.openrepos.org) and create it. Leave automatic certificate management (Let's Encrypt) enabled.

GitLab now shows a verification code. Copy it — the next step needs it.

2. Claim the subdomain with the TXT record

Add the claim to register.json with the CNAME target <namespace>.gitlab.io and the verification TXT record:

"openrepos.org": {
  "awesome-project": {
    "repo": "https://github.com/octocat/awesome-project",
    "target": "awesome-project.gitlab.io",
    "txt": {
      "name": "_gitlab-pages-verification-code",
      "value": "gitlab-pages-verification-code=<your code from GitLab>"
    }
  }
}

The record OpenRepos creates is _gitlab-pages-verification-code.awesome-project.openrepos.org TXT — exactly the name GitLab asks for. Add the badge to your README and open the pull request.

3. Verify and get HTTPS

After merge, DNS sync creates the CNAME and the TXT record. GitLab verifies periodically; to check immediately, open Deploy → Pages, open the domain and choose Verify ownership. You can confirm the record with dig _gitlab-pages-verification-code.awesome-project.openrepos.org TXT.

Once verified, GitLab issues the Let's Encrypt certificate automatically. The domain status moves from unverified to active, and HTTPS starts working shortly after.

Troubleshooting

  • Verification keeps failing — check the TXT record with dig. The value must include the gitlab-pages-verification-code= prefix and the exact code; DNS changes may take a few minutes to propagate.
  • Domain removed after 7 days — GitLab.com removes unverified domains. Fix the record, then re-add the domain in GitLab and claim it again with the new code.
  • Certificate pending — GitLab issues it only after the domain is verified and the CNAME points at <namespace>.gitlab.io. Keep automatic certificate management enabled.
  • The subdomain shows the OpenRepos page — the claim is not merged yet, or DNS has not propagated; explicit CNAMEs take precedence over the wildcard redirect once they exist.

Frequently asked questions

Why does GitLab require a TXT record?

GitLab verifies domain ownership before serving a custom domain, to prevent domain hijacking. The TXT record must contain the code GitLab shows for your project, or the domain is removed after 7 days.

Which target should I use?

Your GitLab namespace host: <namespace>.gitlab.io — that is the Pages server host for your project. The CNAME is allowlisted as *.gitlab.io.

Who issues the certificate?

GitLab does, with Let's Encrypt, once the domain is verified and the DNS record points at <namespace>.gitlab.io. Keep automatic certificate management enabled when you create the domain.

What happens if verification fails?

On GitLab.com, unverified domains are removed from the project after 7 days. Fix the TXT record and use Retry verification in Deploy → Pages before that window ends.

Next steps

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