Resolving GitHub Pages HTTPS Certificate Roadblocks: A Boost for Developer Productivity

In the world of software development, friction points in deployment and infrastructure setup can significantly impact developer productivity metrics. A common scenario that often causes headaches is setting up custom domains with HTTPS on platforms like GitHub Pages. When certificates get stuck, it not only delays project launches but also consumes valuable developer time. This community insight delves into a specific instance of this challenge and offers practical solutions.

Illustration of a developer troubleshooting GitHub Pages HTTPS with Cloudflare DNS settings.
Illustration of a developer troubleshooting GitHub Pages HTTPS with Cloudflare DNS settings.

The HTTPS Certificate Conundrum on GitHub Pages

A developer, spstepp, encountered a persistent issue with two GitHub Pages sites: cashratewatch.com and houseformstudios.com. Despite their sites building and serving correctly over HTTP, neither could obtain an HTTPS certificate. The GitHub Pages API consistently reported the https_certificate state as "authorization_created", rendering the "Enforce HTTPS" option unavailable.

https_certificate state "authorization_created"

spstepp described multiple attempts to resolve the issue, including removing and re-adding custom domains several times over weeks. Their DNS was managed in Squarespace, with the correct GitHub Pages A records and a www CNAME pointing to spstepp.github.io. Crucially, they had no AAAA or CAA records, which are common points of investigation.

A clean developer workspace symbolizing successful deployments and enhanced productivity.
A clean developer workspace symbolizing successful deployments and enhanced productivity.

Unmasking the Root Cause: The Cloudflare Proxy

The breakthrough came from another community member, Manishram-ai, who performed an external DNS lookup. The diagnosis revealed that both domains were unexpectedly using Cloudflare nameservers (e.g., decker.ns.cloudflare.com, sandy.ns.cloudflare.com) and resolving to Cloudflare proxy addresses (104.21.x.x, 172.67.x.x) instead of GitHub's expected IP addresses (185.199.108-111.153). This proxying was the core of the problem.

When Cloudflare's proxy (often indicated by an orange cloud icon in Cloudflare DNS settings) is active, GitHub's certificate authority sees Cloudflare's infrastructure, not the GitHub Pages servers. This prevents GitHub from completing the domain verification process required to issue its own HTTPS certificate, leaving it stuck at authorization_created.

Two Paths to HTTPS: Leveraging Cloudflare or GitHub's Certificate

The solution depends on whether Cloudflare's proxying is intentional or not. Both approaches effectively secure your site with HTTPS, contributing positively to software productivity metrics by ensuring secure deployments.

Option 1: Embrace Cloudflare's HTTPS

If you intentionally use Cloudflare for its performance and security benefits, your visitors are likely already experiencing HTTPS. Cloudflare issues its own certificate for your domain. In this scenario, you don't need GitHub's certificate at all. The key is to ensure Cloudflare's SSL/TLS encryption mode is set to "Full". Avoid "Full (strict)" mode, as GitHub Pages serves content using its generic *.github.io certificate, which "Full (strict)" would reject, leading to a 526 error.

Option 2: Obtain GitHub's Own Certificate

If you prefer GitHub to manage your certificate, you'll need to disable Cloudflare's proxy for your custom domain. This involves switching the apex A records and the www CNAME in Cloudflare to "DNS only" (represented by a grey cloud icon). After making this change, it's crucial to wait for DNS propagation. You can verify this by using a tool like dig +short yourdomain.com to confirm it resolves to GitHub's IP addresses (185.199.x.153).

Once DNS has propagated, navigate to your GitHub repository's Settings > Pages, remove the custom domain, and then re-add it. If the certificate still remains stuck at authorization_created an hour or two after clean DNS propagation, it indicates that GitHub might need to manually reset the certificate request on their end, as you've already performed the necessary steps.

Key Takeaways for Enhanced Developer Workflow

This discussion highlights the critical role of understanding DNS and proxying configurations in maintaining smooth deployment pipelines. Misconfigurations, even subtle ones like an active Cloudflare proxy, can halt progress and impact kpi engineering related to deployment speed and efficiency. By proactively managing DNS settings and understanding how different services interact, developers can significantly reduce friction and boost their overall productivity.

|

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

 Install GitHub App to Start
Dashboard with engineering activity trends