How do I use a custom domain with pages.gay?

Create a .domains file in the same branch as your page's content, containing the domain you want to use, then point your DNS at pages.gay. For subdomains, add a CNAME record to [branch].[repo].[user].pages.gay. For apex domains, where CNAME records don't work, add an A record to 213.210.34.143, an AAAA record to 2a0f:9400:6906:1977::143, and a TXT record containing [branch].[repo].[user].pages.gay.

Step 1: Add the domain to your repository

In the branch that holds your page's content, create a file named .domains. Put the domain you want to use inside it.

The file must live in the same branch as the content it applies to. If your site is served from the pages branch, the .domains file goes there too — not on main.

Step 2: Choose your DNS records based on domain type

The record type depends on whether you're using a subdomain (like www.example.com) or an apex/root domain (like example.com).

Replace [branch], [repo], and [user] with your actual branch name, repository name, and git.gay username. For example, if your user is alice, the repo is blog, and the branch is pages, the CNAME target is pages.blog.alice.pages.gay.

Why apex domains need three records

CNAME records can't be placed at the apex of a domain, so pages.gay uses A and AAAA records to route traffic to its servers directly. The TXT record carries the same [branch].[repo].[user].pages.gay value so the service can verify which site the domain belongs to.

Step 3: Wait for DNS and cache

After saving your DNS changes, propagation can take time depending on your registrar. pages.gay also uses a cache, so updates may not appear for a few minutes. If your changes aren't showing, hard-refresh with Ctrl + Shift + R to force a cache update.

Common issues

• .domains file in the wrong branch — it must sit in the same branch as the page content, or the domain won't be associated with the site.
• CNAME used on an apex domain — most DNS providers reject this. Use the A, AAAA, and TXT combination instead.
• Placeholder values left in — [branch].[repo].[user] must be replaced with your real values in both the .domains file and the DNS records.
• Changes not appearing immediately — this is usually the cache, not a misconfiguration. Hard-refresh before troubleshooting further.

If you're self-hosting pages.gay on your own Gitea or Forgejo server, the setup follows the same pattern, but you'll need to follow the project's docs for the server-side configuration.