CNAME-only configuration fails HTTPS certificate deployment unless A record exists

[ykla]

Select Topic Area

Bug

Body

CNAME-only configuration fails HTTPS certificate deployment unless A record exists

Description

When configuring a custom domain (e.g., xxxx) with only a single CNAME record pointing to <username>.github.io, HTTPS certificate deployment fails unless an A record also exists for the domain.

This behavior has been reproduced using DNS providers such as Cloudflare（no proxy or proxy）, EdgeOne, and DNSPod.

DNS Configuration

Initial configuration (failing case):

xxxx    CNAME    <username>.github.io

No A record exists.

Observed Behavior

1. HTTPS certificate deployment does not complete properly.

2. The system reports:

   Certificate already exists for xxxx and is usable
   

3. Accessing https://xxxx:

   • The browser shows that the certificate is valid.
   • However, the connection is marked as not secure.

4. The system also reports that DNS records cannot be detected.

Workaround

After adding an A record pointing to 8.8.8.8 (Google Public DNS):

xxxx    A    8.8.8.8

HTTPS certificate deployment immediately succeeds and DNS detection works correctly.

Expected Behavior

• A CNAME-only configuration pointing to <username>.github.io should be sufficient for:

  • DNS record detection
  • HTTPS certificate issuance and validation

• The system should not require an unrelated A record for certificate deployment to function properly.

Additional Notes

• The issue appears independent of DNS provider.
• The A record does not serve traffic and is only used to trigger correct certificate behavior.
• This suggests that DNS validation logic may incorrectly require an A record for root/apex domain validation.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[mecodeatlas]

Hi there, @ykla! 👋

Thanks for the detailed report.

Based on the current GitHub Pages documentation, the recommended DNS configuration depends on whether you're using a root domain or a subdomain. A CNAME-only setup is supported for subdomains, but root domains require specific A records pointing to GitHub Pages.

You can review the official guidance here: Configuring a custom domain for your GitHub Pages site

We recommend aligning the DNS configuration with the documented setup and removing any unrelated records. If the issue persists after that, feel free to share more details.

Hope it helps!

[ykla]

Hi there, @ykla! 👋

Thanks for the detailed report.

Based on the current GitHub Pages documentation, the recommended DNS configuration depends on whether you're using a root domain or a subdomain. A CNAME-only setup is supported for subdomains, but root domains require specific A records pointing to GitHub Pages.

You can review the official guidance here: Configuring a custom domain for your GitHub Pages site

We recommend aligning the DNS configuration with the documented setup and removing any unrelated records. If the issue persists after that, feel free to share more details.

Hope it helps!

I feel you may not have read my message carefully. I’m using only a subdomain, and no matter how I configure it, DNS HTTPS doesn’t work properly. It seems that an A record must be assigned to the root domain—pointing to somewhere—only then can the subdomain be successfully directed to GitHub Pages.

[PSMatheus01]

I read through your issue carefully, and I think the maintainer's response missed the point — you're clearly talking about a subdomain, not an apex domain. A subdomain with a CNAME pointing to <username>.github.io is exactly what GitHub's own docs recommend, so you shouldn't need any A record at all.

What you're describing sounds like a bug in GitHub Pages' DNS validation logic. Here's what I think is happening under the hood:

When you set a custom domain in Pages settings, GitHub runs a DNS check before provisioning the Let's Encrypt certificate. For subdomains, it should only need to verify the CNAME resolves to *.github.io. But it seems like the validation is also checking the apex domain — and if the apex has no records at all (no A, no AAAA, nothing), the DNS check fails or gets stuck, which blocks certificate provisioning.

The fact that adding a dummy A record on the apex (even 8.8.8.8, which has nothing to do with GitHub) immediately fixes it strongly suggests the validation logic is doing a lookup on the apex domain as part of its process, and an NXDOMAIN or empty response for the apex is being treated as a failure condition. That's not correct behavior — a subdomain should be independently validatable.

A few things you can try as proper workarounds (instead of pointing at 8.8.8.8):

1) If you own the apex domain and don't use it for anything else, add the actual GitHub Pages A records to the apex:

185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153

This way the apex resolves to GitHub's IPs (which is at least semantically correct), and your subdomain CNAME continues to work as expected. The cert should provision immediately after that.

2) After adding the custom domain in Pages settings, try removing it, waiting a minute, and re-adding it. Sometimes this kicks the certificate provisioning process to retry the DNS check fresh. Combined with the apex A records above, it tends to work.

3) If you've done all of that and the DNS check is still stuck, open a support ticket with GitHub. This is a real bug in their validation logic — a subdomain CNAME should not depend on the apex domain having records. You've already done the hard debugging work (reproducing across Cloudflare, EdgeOne, and DNSPod), so you have solid evidence.

Honestly I think you should file this as a bug regardless, because pointing the apex at 8.8.8.8 "fixing" the issue is a clear sign their DNS check is doing something it shouldn't.

[krillmango]

Keep in mind records you add to the APEX domain factor in the ironically fraudulent anti-fraud service metrics most notably IPQualityScore.com: they take delight in false positives. All records changes are forever recorded in many elsewheres.

Does the APEX A-RR need be public routable?

[Rajveer-code]

This is likely related to how apex (root) domains are handled in DNS + GitHub Pages validation, rather than a strict requirement for an A record itself.

A few key points that explain what you’re seeing:

1. CNAME at the apex isn’t universally supported

For root domains (e.g., example.com), standard DNS technically doesn’t allow a pure CNAME.

Some providers (Cloudflare, DNSPod, etc.) simulate this using:

ANAME / ALIAS / flattening

But GitHub’s validation system may not always interpret these consistently.

2. GitHub Pages expects resolvable A/AAAA at the apex

For apex domains, GitHub officially recommends:

A 185.199.108.153
A 185.199.109.153
A 185.199.110.153
A 185.199.111.153

Even if a provider “supports” CNAME at root, GitHub’s certificate/DNS checks often rely on direct A/AAAA resolution.

3. Why your 8.8.8.8 workaround “works”

Adding:

A 8.8.8.8

doesn’t actually route traffic correctly, but it:

makes the domain resolvable via A record
satisfies GitHub’s DNS detection logic
allows the certificate process to proceed

So it’s acting as a validation bypass, not a proper fix.

4. Why HTTPS looks “half-working”
   Certificate exists → TLS layer is fine
   But DNS validation / routing mismatch → browser flags issues

So you get a valid cert but inconsistent “secure” status.

5. Recommended fix (proper setup)

For apex domain:

A 185.199.108.153
A 185.199.109.153
A 185.199.110.153
A 185.199.111.153

For subdomain (e.g., www):

CNAME .github.io
6. Why this feels like a bug

You’re not wrong — the confusing part is:

Some DNS providers do allow CNAME-like behavior at root
But GitHub’s validation logic doesn’t fully align with that

So it looks like:

“CNAME should work, but GitHub still expects A records”

TL;DR
Apex domains need A records for GitHub Pages (even if CNAME seems supported)
Your 8.8.8.8 workaround works only because it satisfies DNS detection
Proper fix is to use GitHub’s official A records

Definitely a valid DX issue — the system could communicate this requirement much more clearly 👍