Use your own domain for a Gitback Board

A custom domain lets a Client serve their Gitback Board from a hostname they own, such as feedback.acme.com, instead of gitback.us/github/<owner>/<repo>. It is a Pro feature, it takes one DNS record, and End Users can still sign in and vote on the Client's domain without their GitHub token ever being readable there.

This page describes what the code does today, including what it does not do yet.

What does a custom domain do for a Board?

It serves the whole Board, every Module, from your hostname, and makes that hostname the Board's canonical address. The Board is not copied: your domain renders the same Board layout, fed by the same repository, with the Board chosen from the request's Host header.

Gitback's proxy decides what your domain answers, by string comparison and nothing else. On a custom host:

Because every other path is rewritten under the host pages, your domain cannot be used to reach another Board, Gitback's landing page or /pricing; those come back not found. A custom host is not a second door into Gitback's API.

Once a domain is attached, the Board's pages on gitback.us keep serving but name your domain as canonical, and your domain names itself. The Board then drops out of the gitback.us Board sitemap, so crawlers are not sent to the copy that says it is not the real one.

Which plan includes a custom domain?

Custom domains are on the Pro Plan and above, which means Pro and Ultimate. The Free Plan, which covers unlimited open-source Boards, does not include one. Current prices are on the pricing page.

The Plan is checked when you attach, on the signed-in Account, before anything is sent to Vercel or written down. If the Account is below Pro, the settings pane replaces the form with "Custom domains are on Pro and above", names the Plan you are on, and links to the Board's plans. Removing a domain is never gated.

How do you attach a custom domain, step by step?

Attach it from the Board's settings on gitback.us, as the Board's Client. Only an account GitHub reports as having write access to the repository can open the settings or change the domain; anyone else is sent back to the Board. If you have not claimed your Board yet, start with open a Board and claim it.

1. Open your Board on gitback.us. Under the Module cards, the Settings strip has a Custom domain link.
2. In the Custom domain pane, type the hostname, for example feedback.acme.com, and press Save. A subdomain is the easier choice; the form warns that a root domain like acme.com needs an A record, which some DNS providers make awkward.
3. Gitback checks, in this order: that you are the Board's Client, that your Plan allows it, that the hostname is valid, that this Board has no domain yet, and that no other Board holds this hostname. Only then does it add the domain to Gitback's Vercel project and record it.
4. The pane now shows the domain as Pending with the record to add. Add it at your DNS provider (next section).
5. The pane re-checks every 20 seconds while the page is visible, for up to 10 minutes. After that it stops and says DNS can take up to 48 hours; press Check now to ask again.
6. When Vercel reports the domain verified and configured, the badge reads Active and the hostname becomes a link to your live Board.

If step 3 fails, the pane says why in plain words: another Board's domain shows as Taken, and a Board that already has a domain tells you to remove that one first.

What DNS record does a custom domain need?

A CNAME record for a subdomain, or an A record for a root domain, with the value the settings pane shows. Gitback does not print a fixed value here or anywhere else, because Vercel now assigns record values per project; the pane shows exactly what Vercel named for yours, with a copy button.

The Name column is written relative to your domain: feedback for feedback.acme.com, and @ for the root domain itself. Putting the full hostname in the Name field is a common mistake.

Some domains need a step first. If Vercel wants proof that you own the domain, the pane asks for a TXT record, with the name and value Vercel gives, before anything else. If the domain is in use on another Vercel project, verifying it here moves it to this Board and it stops working there.

The pane also lists three things that commonly stall a domain:

• Remove any other A, AAAA or CNAME records for the hostname. A leftover AAAA record stalls the certificate.
• Edit DNS where the domain's nameservers point, which is not always where you bought it.
• If the domain has CAA records, add one allowing 0 issue "letsencrypt.org".

If the domain sits behind a proxy such as Cloudflare, the pane shows Needs attention. Switch the record to DNS only, or set SSL/TLS to Full (strict); Flexible causes a redirect loop.

How does sign-in work on your own domain?

End Users sign in on gitback.us and confirm your domain by hand, and your domain then holds a short-lived, sealed grant that only Gitback can open. Gitback's ADR 0011 chose this design because you own the domain: you could put your own CDN in front of it and read every cookie and request line there, so the End User's GitHub token must never sit on your domain in the clear.

1. The End User presses sign in on your domain. That is a form POST to a server action, never a plain link, so another website cannot start it.
2. Their browser goes to a confirmation page on gitback.us: "Sign in to feedback.acme.com?", naming the account and the Board, and saying the domain keeps this for up to 8 hours.
3. On Continue, gitback.us seals a transport grant, valid for at most 60 seconds, and redirects to /api/auth/redeem on your domain.
4. Your domain checks the grant was sealed for this host and re-seals it as a cookie that lasts at most 8 hours, answered with Cache-Control: no-store, private.

The grant is encrypted with AES-256-GCM and bound to your hostname, so a cookie copied from your domain cannot be used on another Board. A grant is only minted from an End User sign-in whose GitHub scopes stay inside the End User set. A visitor signed out, or signed in as a Client, is sent to sign in as an End User first; a session carrying a broader scope, such as a maintainer's repo token, is refused. Every vote, post and comment is still written to GitHub by the End User's own account.

The confirmation page appears every time a grant is minted, with no exceptions. Your domain skips the handoff only while it already holds a live grant, so a returning End User sees it about once per 8 hours.

How do you remove a custom domain?

Press Remove on the domain's card in the same settings pane, then confirm. Gitback removes the domain from its Vercel project first and deletes its own record second, so if Vercel refuses, nothing is lost and you can retry from the same card. Your Board stops answering on the hostname on its next request, and serves at its gitback.us address as before.

Then delete the CNAME or A record at your DNS provider. The confirmation dialog says so because a record left pointing at Vercel can let someone else take the hostname over.

What does a custom domain not do yet?

These gaps are in the code on the branch today:

• One domain per Board. A Board cannot answer on two hostnames, such as with and without www. This one is a decision and will stay: the Board is the unit, and a Client with three repositories can give each Board its own domain.
• No sitemap, robots file or markdown versions on your domain. Your domain serves the Board's pages only. The gitback.us Board sitemap leaves out Boards with a domain, and a sitemap for your own host is not built yet.
• Client tools stay on gitback.us. Claiming, pricing, Theme and the settings pane have no pages on your domain, and the Client stays signed out there. Manage the Board from gitback.us.
• Signing out on gitback.us does not end a grant on your domain. The grant lives in a cookie with no server-side record, so it dies at its expiry, within 8 hours. This trade-off was accepted in ADR 0011 in exchange for keeping no token table.
• A private Board is read-only on its domain. No grant is issued for it and it shows no sign-in control, because End Users have no access to a private repository and Gitback does not write on their behalf.
• Two states the pane cannot show. It does not report conflicting DNS records or a certificate still being issued, because the Vercel calls Gitback makes return no data for either.

For what else a Board does, see features, or browse the rest of the docs.