Mastering GitHub Pages SSL: Resolving `bad_authz` for Custom Domains

Maintaining a secure and accessible website is a critical responsibility for any development team, directly impacting key metrics for engineering teams such as site reliability and user trust. When a custom domain on GitHub Pages encounters an SSL certificate error like bad_authz, it can disrupt service and signal underlying configuration issues. This community insight delves into a common scenario involving Cloudflare and GitHub Pages, offering a clear path to resolution.

Diagram illustrating DNS resolution paths for a custom domain, with and without Cloudflare proxying, highlighting where validation can be intercepted.
Diagram illustrating DNS resolution paths for a custom domain, with and without Cloudflare proxying, highlighting where validation can be intercepted.

The `bad_authz` Dilemma: A GitHub Pages Certificate Stuck

A user, hotboxking09, reported a persistent bad_authz state for their custom domain jarvisserver.org on GitHub Pages. Despite their site being reachable via Cloudflare, direct TLS verification failed, revealing an expired origin certificate. The GitHub Pages API confirmed the bad_authz state with an expired timestamp:

{
  "state": "bad_authz",
  "description": "The ACME authorization is in a bad state. We need to start over.",
  "domains": ["jarvisserver.org", "www.jarvisserver.org"],
  "expires_at": "2026-10-20"
}

Hotboxking09 had already attempted several troubleshooting steps, including temporarily disabling Cloudflare proxying, confirming DNS health, and repeatedly removing and re-adding the custom domain. However, restoring Cloudflare's proxy flags prematurely seemed to prevent the certificate issuance from completing.

A developer successfully troubleshooting and resolving a custom domain SSL certificate issue, indicated by a green padlock on their screen.
A developer successfully troubleshooting and resolving a custom domain SSL certificate issue, indicated by a green padlock on their screen.

The Root Cause: Cloudflare Proxying Interferes with Let's Encrypt

Community member GgauravJ05 quickly identified the core problem: GitHub Pages relies on Let's Encrypt for automatic SSL certificate issuance. For validation to succeed, Let's Encrypt's challenge requests must directly reach GitHub's servers for both the apex domain and its www subdomain. When Cloudflare's proxy is active, it intercepts these requests, preventing them from reaching GitHub and thus stalling the authorization process in a bad_authz state.

The Solution: A Coordinated DNS-Only Window

The fix involves creating an uninterrupted window where DNS points directly to GitHub Pages, allowing Let's Encrypt to validate and issue the certificate. Here’s the step-by-step process:

  1. Disable Cloudflare Proxying: In your Cloudflare DNS settings, set the four apex A records (pointing to GitHub's IPs: 185.199.108.153 through 185.199.111.153) and the www CNAME (pointing to yourusername.github.io) to DNS only (grey cloud icon). Leave them in this state.

  2. Verify DNS Propagation: Wait until public DNS records reflect GitHub's IPs. You can check this using a command like:

    dig +short jarvisserver.org

    You should see GitHub's IP addresses (e.g., 185.199.108–111.153).

  3. Reset Custom Domain in GitHub Pages: Navigate to your repository's Settings → Pages. Remove the custom domain, save the changes, and then re-add your custom domain (e.g., jarvisserver.org) again.

  4. Monitor Certificate Status: Do not re-enable Cloudflare proxying yet. Instead, poll the certificate status using the GitHub API. This can be done with the gh CLI or a direct API call:

    gh api repos/hotboxking09/jarvis-systems-website/pages --jq .https_certificate

    Wait for the state to change to approved or issued with a new expires_at. Once successful, tick the Enforce HTTPS option.

  5. Re-enable Cloudflare Proxy (Optional): Only after successful certificate issuance, if you wish to use Cloudflare's proxy, you can turn the proxy back on (orange cloud). Ensure your Cloudflare SSL/TLS encryption mode is set to Full (strict) to maintain end-to-end encryption.

Long-Term Considerations and Escalation

It's important to note that certificate renewals happen roughly every 90 days. If you keep Cloudflare proxied, you might need to repeat steps 1-4 before each expiry to ensure smooth renewals. Understanding this process is crucial for maintaining consistent site availability, a key operational metric for engineering teams.

If, after 24 hours of following these steps with DNS-only enabled the entire time, the certificate remains in a bad_authz state, then the order might be stuck on GitHub's side. At that point, reopening a Support ticket with a detailed timeline of your attempts would be appropriate.

|

Dashboards, alerts, and review-ready summaries built on your GitHub activity.

 Install GitHub App to Start
Dashboard with engineering activity trends