Skip to content

docs(readme): record the TLS configuration and why Full (strict) must not be restored - #229

Merged
jakebromberg merged 1 commit into
mainfrom
docs/tls-origin-cert-config
Aug 26, 2026
Merged

docs(readme): record the TLS configuration and why Full (strict) must not be restored#229
jakebromberg merged 1 commit into
mainfrom
docs/tls-origin-cert-config

Conversation

@jakebromberg

Copy link
Copy Markdown
Member

Adds a TLS & certificates section to the README, next to the existing DNS & hosting note.

Why

The GitHub Pages origin certificate for wxyc.org is stuck at https_certificate.state: "bad_authz" ("The ACME authorization is in a bad state. We need to start over.") and has not renewed. Only GitHub can clear that state, and the WXYC org is on GitHub Free, whose support form offers no Pages category — so there is no ticket path and this will persist for a while.

The operational consequence is a trap: #209 instructs that the Cloudflare SSL/TLS mode must be Full (strict), and that issue is closed, so it is what the next reader inherits. Full (strict) validates the origin certificate — meaning that restoring it would turn the 2026-09-19 expiry into a full site outage (526). The zone is currently on Full (non-strict), which is what keeps the expiry harmless. That reasoning lived only in issue comments; this puts it where someone changing the setting will actually see it.

What the section records

  • There are two certificates (Cloudflare edge vs. GitHub origin), and how to read the origin one now that the proxy hides it.
  • The origin renewal is broken, the ACME challenge path is not the cause (verified for both wxyc.org and www.wxyc.org, no CAA records), and only GitHub can fix it.
  • Do not set Full (strict) until the certificate is confirmed reissued — explicitly superseding Apex cutover stage 1: proxy wxyc.org + www through Cloudflare (flip, hygiene, soak) #209's preflight instruction.
  • Do not detach/re-add the custom domain to try to fix it: tested at both an immediate re-add and a 20-minute gap, GitHub restores the identical bad_authz record either way, and the detach poisons GitHub's Fastly cache per-path with 404s that outlive their own max-age. Includes the origin-direct Host: header verification technique that avoids creating those cache entries.
  • The two settings that now depend on this and should be left alone: Cloudflare Always Use HTTPS (serving the http→https redirect, because https_enforced is stuck false and cannot be re-enabled while the certificate is unissued) and the www Page Rule (replacing GitHub's www→apex canonicalization).

Notes

  • README-only; no code paths touched. prettier --check passes (the addition initially failed it and was reformatted).
  • Full context and the investigation log are in #209.

… not be restored

The origin certificate's ACME renewal is stuck at bad_authz and only GitHub can clear it. Until it is fixed, the Cloudflare SSL/TLS mode must stay on Full (non-strict) — Full (strict) validates the origin certificate, so the 2026-09-19 expiry would take the site fully offline with a 526. #209's preflight instruction to use Full (strict) predates this and is superseded.

Also records the two settings that now depend on this (Always Use HTTPS at the edge replacing the stuck https_enforced, and the www Page Rule replacing GitHub's canonicalization), and documents that detaching the custom domain does not clear bad_authz at any duration while poisoning GitHub's Fastly cache per path.
@jakebromberg
jakebromberg merged commit b35ab05 into main Aug 26, 2026
1 check passed
@jakebromberg
jakebromberg deleted the docs/tls-origin-cert-config branch August 26, 2026 18:55
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