Skip to content

docs: status page custom domain certificates and renewal - #792

Merged
hlenke merged 5 commits into
mainfrom
docs/status-page-custom-domain-certs
Nov 7, 2026
Merged

hlenke merged 5 commits into
mainfrom
docs/status-page-custom-domain-certs

Conversation

@hlenke

@hlenke hlenke commented Nov 7, 2026

Copy link
Copy Markdown
Member

What changed

Updates communicate/status-pages/custom-domain.mdx:

  • The TXT step is now conditional: new domains validate their certificate over HTTP, so the CNAME record is usually all you need. Add TXT records only if Checkly shows them.
  • The first step now tells you to save the status page to see the DNS records, and the last step points to Refresh domain status and the green check that marks a verified domain.
  • Removed the note that search engines require the TXT verification, since TXT records are no longer needed for most domains.
  • New section Certificate renewal and troubleshooting: automatic renewal, keeping the CNAME pointing to Checkly, CAA records, what each certificate message in the status page settings means and what to do, removing and re-adding the domain as a last resort, and the email Checkly sends when a certificate can't be issued or renewed.

Why

The page told every user to add TXT records, which no longer matches how custom domain certificates are issued. Users regularly hit certificate validation and renewal questions, and the page had no guidance on renewal or on the messages shown in the app.

Verified against the product code; certificate issuance and renewal can't be exercised locally.

Checks

  • python3 .github/scripts/check_frontmatter.py: passed
  • npm run check:anchors: passed
  • npm run check:links: passed
  • npx mint broken-links: no broken links
  • node .github/scripts/check-redirect-destinations.mjs and sitemap regeneration: passed, no changes

🤖 Generated with Claude Code

New custom domains validate their certificate over HTTP with only the
CNAME record, so the TXT step is now conditional. Adds a section on
automatic renewal, CAA records, the certificate messages shown in the
status page settings, and the renewal emails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
checkly-422f444a 🟢 Ready View Preview Nov 7, 2026, 9:17 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hlenke

hlenke commented Nov 7, 2026

Copy link
Copy Markdown
Member Author

Removed the sentence about certificate problem emails: whether those emails are sent in production couldn't be confirmed from the code, so the page no longer promises them.

@hlenke hlenke left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs changes · The setup steps and the quoted messages match the app. Before merging, limit the automatic-renewal claim to HTTP-validated domains and list the second certificate-failure message.

CI passes, the PR merges cleanly, and main hasn't changed communicate/status-pages/custom-domain.mdx since the merge base. The only other open PR on this file is draft #774 (sentence case), which changes the frontmatter title only. The new ## Certificate renewal and troubleshooting heading already uses sentence case, so the two shouldn't conflict. The new section goes at the end, after the setup steps, which is the right place.

The PR description says the new section covers "the email Checkly sends when a certificate can't be issued or renewed", but the diff doesn't mention an email. Add it if that's intended, or update the description.

Inline: 2 important, 1 wording.

What I checked
  • Read the full diff from the merge base 7da4a04 and the whole page at the PR head.
  • gh pr checks 792: all 6 checks pass. gh pr view: MERGEABLE / CLEAN. git log <base>..origin/main -- communicate/status-pages/custom-domain.mdx: no new commits. pr_impact.py: no cross-file findings. Searched all .mdx on main for other custom domain, TXT and CAA setup instructions and found none outside this page.
  • Checked against source (monorepo origin/main@2d79b98589):
    • New custom hostnames are created with HTTP domain control validation. HTTP-validated hostnames renew without DNS changes, while TXT-validated ones needed new records at renewal: apps/backend/api/src/common/services/status-pages/lib/cloudflare-hostname-service.ts.
    • Records listed after saving (the CNAME, plus the ownership TXT and any TXT validation records Cloudflare returns), the save prompt, the green check (shown only once the hostname and certificate are active), and Refresh domain status: apps/webapp/src/pages/status-pages/status-pages-editor/StatusPageEditorCustomDomain.vue. The CNAME target custom-domain.checkly-status-page.com comes from configuration and matches the existing step.
    • The four quoted messages match the UI copy in apps/webapp/src/pages/status-pages/StatusPage.i18n.ts, quoted up to the first sentence. The "usually takes a few minutes" timing and "start a new certificate order" also match that copy. The same file has a fallback validation-failure message and a read-only variant of the timeout message.
    • The "Cloudflare has not returned the certificate validation records yet" message only appears for domains that aren't HTTP-validated.
  • Could not verify: how often Cloudflare returns an ownership TXT record for new HTTP-validated domains. The UI lists that record whenever Cloudflare returns one, so readers may still see a TXT row. "Add them if Checkly shows them" covers that case. I also couldn't confirm the certificate email mentioned in the description in source.
  • No end-to-end test: certificate issuance and renewal go through Cloudflare and can't be exercised against local Checkly.

@hlenke
hlenke enabled auto-merge (squash) November 7, 2026 21:17
@hlenke
hlenke merged commit ae77f55 into main Nov 7, 2026
6 checks passed
@hlenke
hlenke deleted the docs/status-page-custom-domain-certs branch November 7, 2026 21:20

This branch was successfully deployed

1 active deployment
staging — bb4fc633 Deployed Nov 7, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant