Custom domain SSL renewal: does GitBook auto-renew the Let's Encrypt certificate, or must the domain be re-added?

Short answer

GitBook's custom-domain flow is built on automated ACME provisioning, and platforms of this type renew Let's Encrypt certificates automatically as long as your DNS still points at GitBook. You should not need to remove and re-add the domain for a normal renewal cycle. That said, GitBook's public documentation does not spell out the renewal lifecycle in detail, so treat the auto-renewal behavior as the strongly likely design rather than a contractually confirmed fact, and verify it against your own certificate dates.

Why auto-renewal is the expected behavior

A few facts are solid:

• Let's Encrypt certificates are valid for 90 days, and the entire ACME ecosystem is designed around unattended renewal — typically attempted around day 60.
• GitBook provisions the certificate automatically at setup time once your CNAME or A record resolves correctly, which means the renewal path uses the same machinery: as long as the HTTP-01 or TLS-ALPN challenge can reach GitBook's servers via your DNS, renewal succeeds without you doing anything.
• The "Active" badge in your workspace's domain settings reflects a currently valid, correctly routed certificate — it is a state indicator, not a one-time issuance flag.

Re-adding the domain is a recovery action, not routine maintenance. In fact, repeatedly removing and re-adding a domain in a short window can trip Let's Encrypt's duplicate-certificate rate limits, so it is something to avoid unless renewal has actually failed.

When renewal can fail

Renewal breaks for the same reason initial issuance breaks: the ACME challenge can no longer reach GitBook through your domain. Common causes:

• DNS records changed after setup (moved providers, added a proxy like Cloudflare in front, or the CNAME now points elsewhere).
• A CAA record added to the zone that doesn't include letsencrypt.org.
• DNS propagation issues coinciding with the renewal attempt.

If renewal fails, expect the badge to regress toward a "Pending SSL" or error state and, eventually, browsers to show certificate-expired warnings. Whether GitBook proactively emails workspace owners about an impending custom-domain certificate failure is not clearly documented — don't rely on a notification; monitor it yourself.

How to verify without waiting months

You can confirm the rotation behavior within about 30 days:

1. Open your published docs site, click the padlock in the browser, and view the certificate. Note the "Valid from" and "Valid to" dates.
2. Record today's date and the expiry. If issuance was recent, the "Valid from" date tells you when the 90-day clock started.
3. Re-check around day 60–70 after issuance. If the "Valid from" date has moved forward without any action from you, automatic renewal is confirmed for your setup.

For a scripted check, this prints the current dates:

echo | openssl s_client -servername docs.example.com -connect docs.example.com:443 2>/dev/null \
  | openssl x509 -noout -dates

Running that weekly in a cron job or CI schedule gives you an early-warning system: if the expiry date stops moving forward and drops below ~14 days remaining, investigate DNS before it lapses.

If renewal does fail

1. Confirm your CNAME/A record still matches what GitBook's domain settings panel currently shows.
2. Check for a CAA record: dig CAA example.com +short. If present, it must permit Let's Encrypt.
3. If DNS is correct and the badge is stuck, removing and re-adding the domain is the practical recovery step — but do it once, not repeatedly, to avoid rate limits.
4. If it still won't issue, contact GitBook support with the domain and the badge state; re-issuance may need a nudge on their side.

Note: GitBook does not publish a detailed renewal-policy document, so the renewal timing and notification behavior above reflect standard ACME platform practice rather than confirmed GitBook specifics. The certificate-date check described here is the reliable way to confirm it for your own domain.