GitHub Pages

Solving GitHub Pages SSL `bad_authz` with Cloudflare: A Dev Team's Guide to Reliability

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, user trust, and overall operational efficiency. When a custom domain on GitHub Pages encounters a persistent SSL certificate error like bad_authz, it can disrupt service, erode user confidence, and signal underlying configuration issues that demand immediate attention. This insight from the devActivity community delves into a common scenario involving Cloudflare and GitHub Pages, offering a clear, actionable path to resolution for dev teams, product managers, and CTOs.

The bad_authz Dilemma: A Stuck GitHub Pages Certificate

A user, hotboxking09, recently 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 for apex A records and the www CNAME, 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, leaving the site in a precarious state.

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

Community member GgauravJ05 quickly identified the core problem: GitHub Pages relies on Let's Encrypt for automatic SSL certificate issuance. For this 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 (the 'orange cloud' setting) is active, it intercepts these requests. Instead of the validation challenge reaching GitHub's servers, it hits Cloudflare's edge network, which then responds with its own server headers, preventing the necessary authorization from completing.

This interruption means that even if you remove and re-add your custom domain on GitHub Pages (which restarts the ACME order), the validation process will fail if Cloudflare is still proxying the traffic. The certificate remains stuck in bad_authz, and your origin certificate on GitHub Pages expires, impacting your site's security and accessibility.

Network diagram comparing direct DNS resolution to GitHub Pages versus resolution through Cloudflare's proxy, emphasizing the path for SSL certificate validation.
Network diagram comparing direct DNS resolution to GitHub Pages versus resolution through Cloudflare's proxy, emphasizing the path for SSL certificate validation.

The Resolution Path: A Step-by-Step Guide for Engineering Teams

To successfully issue or renew your GitHub Pages SSL certificate when using Cloudflare, a specific sequence of actions is required. This process ensures that Let's Encrypt can validate your domain ownership directly with GitHub's servers.

  1. Disable Cloudflare Proxying (DNS Only): In your Cloudflare DNS settings, set the four apex A records (e.g., 185.199.108.153 through 185.199.111.153) and the www CNAME (pointing to yourusername.github.io) to DNS only. This means clicking the orange cloud icon to turn it grey. Leave them in this state.
  2. Verify Public DNS Resolution: Wait a few minutes for DNS changes to propagate. Use a tool like dig +short jarvisserver.org to confirm that your domain now resolves directly to GitHub's IP addresses (e.g., 185.199.108–111.153) and not Cloudflare's.
  3. Remove and Re-add Custom Domain in GitHub Pages: Navigate to your GitHub repository's Settings → Pages. Remove your custom domain, save the change, then immediately add the custom domain (e.g., jarvisserver.org) again. This action triggers a new ACME certificate order.
  4. Monitor Certificate Status (Patience is Key): Do not re-enable Cloudflare proxying yet. GitHub's documentation states that certificate issuance can take up to an hour, but it can take longer if previous orders have failed. You can poll the GitHub Pages API to check the status:

    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, remember to tick the Enforce HTTPS option in your GitHub Pages settings if it's not already enabled.

  5. Re-enable Cloudflare Proxying (Full Strict SSL): Only after the certificate has been successfully issued and HTTPS is enforced on GitHub Pages, you can re-enable Cloudflare's proxy (orange cloud) for your DNS records. Crucially, ensure your Cloudflare SSL/TLS encryption mode is set to Full (strict). This ensures that Cloudflare encrypts traffic to your origin server (GitHub Pages) using a valid, trusted certificate.

Beyond the Immediate Fix: Proactive Measures for Continuous Delivery

While the steps above resolve the immediate bad_authz issue, it's vital for engineering and delivery managers to understand the long-term implications. Let's Encrypt certificates typically expire every 90 days. This means renewals can fail the same way if Cloudflare's proxy is active during the validation window. To maintain robust tooling and ensure continuous delivery, consider these proactive measures:

  • Scheduled DNS-Only Windows: Plan to temporarily switch to DNS-only mode in Cloudflare before each 90-day expiry. This can be integrated into your team's operational calendar.
  • Automated Monitoring: Implement monitoring for certificate expiry dates for all critical web properties. Tools that leverage git reporting can track changes to DNS configurations or GitHub Pages settings, alerting your team if a proxy is re-enabled prematurely or if an expiry is approaching without a successful renewal.
  • Regular Retrospectives: Incorporate discussions about tooling reliability and certificate management into your team's agile retrospective template. This fosters a culture of learning and allows the team to identify patterns, refine processes, and prevent recurring issues that impact metrics for engineering teams like uptime and MTTR (Mean Time To Resolution).
  • Documentation: Ensure your team's internal documentation clearly outlines this specific procedure for GitHub Pages and Cloudflare, making it easy for any team member to follow.
An agile team conducting a retrospective, discussing operational workflows and preventative measures for certificate renewals and system reliability.
An agile team conducting a retrospective, discussing operational workflows and preventative measures for certificate renewals and system reliability.

Conclusion: Mastering Your Tooling for Peak Performance

The bad_authz certificate error on GitHub Pages with Cloudflare is a common pitfall, but one that can be effectively managed with a clear understanding of how these systems interact. For dev teams, product managers, and CTOs, ensuring the seamless operation of foundational tooling like web hosting and SSL certificates is paramount. It directly contributes to achieving high metrics for engineering teams, fostering user trust, and maintaining a smooth delivery pipeline. By adopting the precise steps outlined and implementing proactive strategies, you can prevent future outages and keep your web properties secure and accessible.

Share:

|

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

 Install GitHub App to Start
Dashboard with engineering activity trends