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/b/<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 Cloudflare 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 a CNAME at the root, which only some DNS providers allow.
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 Cloudflare zone and record it.
4. The pane now shows the domain as Pending with the records 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 Cloudflare has verified the domain, the pane says its certificate is being issued, which usually takes a few minutes. Once Cloudflare reports both the domain and its certificate active, 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 records does a custom domain need?

Two: a CNAME record pointing your hostname at domains.gitback.us, and a TXT record named _cf-custom-hostname with the value the settings pane shows, with a copy button. Gitback serves custom domains through Cloudflare for SaaS, and the CNAME is what sends your hostname's traffic to it. Cloudflare checks the TXT record to confirm you own the domain, so it can verify the domain even before the CNAME resolves.

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

A root domain such as acme.com takes a CNAME at @ as well. Ordinary DNS does not allow a CNAME at the root, so this works only where your DNS provider flattens it, a feature often called CNAME flattening, ALIAS or ANAME. If your provider has none of these, use a subdomain.

Once the domain is verified, Cloudflare issues its certificate on its own, which usually takes a few minutes. If the certificate needs a TXT record of its own, the pane shows it.

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

• Remove any other A, AAAA or CNAME records for the hostname.
• Edit DNS where the domain's nameservers point, which is not always where you bought it.
• If the domain has CAA records, allow letsencrypt.org, pki.goog and ssl.com, the certificate authorities Cloudflare issues from.

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. On a public repository's Board every vote, post and comment is still written to GitHub by the End User's own account; on a private one the Gitback App writes them, naming the End User.

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 Cloudflare zone first, which also revokes its certificate, and deletes its own record second, so if Cloudflare 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 and TXT records at your DNS provider. The confirmation dialog says so because a CNAME left pointing at domains.gitback.us 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:

• A root domain needs a provider that flattens a CNAME. Gitback has no IP address to give an A record, so a root domain works only where the DNS provider supports CNAME flattening, ALIAS or ANAME.
• 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.
• No reason when a domain stalls. The pane does not say which DNS record conflicts or why a certificate is refused. Cloudflare reports both only as its own prose, which the pane does not show, so a domain that stays Pending shows the same three tips.

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