How to Configure a Custom Domain for Codeberg Pages

Updated

To point your own domain at a Codeberg Pages site, you add DNS records at your domain registrar and then authorize Codeberg to serve your repository on that domain. The exact records depend on whether you use a subdomain (where CNAME works) or an apex/root domain (where you need ALIAS, or A + AAAA plus a TXT authorization record). You also need a TXT record under _git-pages-repository so the Codeberg Pages server is allowed to deploy your repository.

Before you start

  • Your site must already be deployed on Codeberg Pages, reachable at https://USERNAME.codeberg.page/REPOSITORY (or https://USERNAME.codeberg.page if the repository is named pages).
  • You need access to your domain's DNS settings.
  • DNS changes can take time to propagate, so verify with a DNS lookup tool if the domain doesn't resolve immediately.

Step 1: Add the DNS record for your domain

The record type depends on the kind of domain you're pointing.

For subdomains (CNAME)

Add a CNAME record:

CNAME codeberg.page.

For apex domains (ALIAS)

If your DNS provider supports ALIAS, use it for the apex domain:

ALIAS codeberg.page.

For apex domains without ALIAS support

If ALIAS isn't supported, add the TXT record described in Step 2, then use A and AAAA records:

A    217.197.84.141
AAAA 2a0a:4580:103f:c0de::2

Step 2: Authorize Codeberg Pages to deploy your repository

Add a TXT record on the subdomain _git-pages-repository. Its value is the Git HTTPS clone URL of your repository:

TXT https://codeberg.org/user/repo.git

Replace user and repo with your actual Codeberg username (or organization) and repository name. This record tells the Codeberg Pages server that it's allowed to deploy your repository to the server.

Step 3: Confirm the setup

Once the records are in place, your site should be served on your custom domain. If you set up deployment via a webhook (the non-CI path), make sure the webhook's Target URL points to your custom domain rather than the default USERNAME.codeberg.page address.

Common issues

  • Apex domain won't resolve with CNAME. CNAME records generally don't work at the apex, which is why ALIAS or A + AAAA are used instead.
  • Missing authorization record. Without the TXT record under _git-pages-repository, the Codeberg Pages server won't deploy your repository to the server.
  • Wrong repository URL in the TXT record. The value must be the Git HTTPS clone URL (https://codeberg.org/user/repo.git), not the Pages URL.
  • Webhook still pointing at the default subdomain. If you use a webhook for deployment, update its Target URL to your custom domain after configuring DNS.