docs

docs copied to clipboard

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https

What part(s) of the article would you like to see updated?

The Enforcing HTTPS for your github pages site dosen't mentioned it will automatically add some CAA records for your custom domain. I thought it was just redirecting requests from port 80 to 443.

This makes it hard to debugging when requesting certificates from other CA ( Try search out 'Verify error:CAA record for XXX prevents issuance' ).

Additional information

The story: I built a website over GitHub Pages, gave it a custom domain and enabled the 'Enforcing HTTPS' function before. Then today my cloud service provider notified me that the SSL certificate I used is nearly expired. So I started requesting new certificates from Let's encrypt with some wildcard subdomains, which covered the one I gave to the GitHub Pages site. And then acme client keeps telling me 'Verify error:CAA record for XXX prevents issuance' when renewing certificate. Finally I remembered that site was hosting on GitHub and it enabled Enforcing HTTPS there. After I disabled the Enforcing HTTPS function, and verified it with dig CAA xxxx, then the certification renew progress continues.

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

@DevDengChao Thanks so much for opening an issue and providing all the details! I'll triage this for the team to take a look :eyes:

@cmwilson21 Any update ?

@DevDengChao Thanks for checking in! This is up on the board and waiting for a writer's review. Someone will have eyes on it soon 👀

I'm researching on this again today as my cert is nearly expired these days. Still cannot renew a certification with acme.sh except disabling the custom domain DNS record.

What I tried:

1. Disabled the "Enforce HTTPS" function in Pages. Then the site is available via both HTTP and HTTPS, but Let's Encrypt still cannot issue a certification as it thought the CAA record for *.xxx.dengchao.fun is preventing issuance.
2. Add CAA record with value 0 issue letsencrypt.org for @.dengchao.fun not works
3. Add CAA record with value 0 issue letsencrypt.org for *.dengchao.fun not works
4. Add CAA record with value 0 issue letsencrypt.org for *.xxx.dengchao.fun not works
5. Add CAA record with value 0 issuewild letsencrypt.org for *.xxx.dengchao.fun not works
6. Disabled CNAME record for xxx.dengchao.fun to xxx.github.io, then it works, let's encrypt is able to give me a new certification.

I have to hosting my site somewhere else before (GitHub solved this problem || I figure out what's going wrong with the CAA records).

@cmwilson21 Help, I have to add subdomains one by one in the certification renew request now, if you could remove the unexpected CAA records or add one more 0 issuewild letsencrypt.org will help me a lot.

Jp[Touchez un extrait pour le coller dans la zone de texte.](https://gboard.app.goo.gl/eRn6x)

@DevDengChao - Thanks for reaching out and providing extra information and the steps you have taken.

A majority of our team are out for the holidays, so this may not get reviewed until their return. If you are needing immediate help, please reach out to our amazing support team. 💛

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:

Any update ?

@DevDengChao GitHub Pages has no access to your DNS zone. When we are enforcing HTTPS, we simply make sure your site is accessed via the HTTPS protocol. If not we make a redirection to make it happen. This is all happening over HTTP not DNS.

If your are getting a Verify error:CAA record for XXX prevents issuance error when trying to issue a TLS certificate for your custom domain, that means you (or your DNS registrar) has defined a CAA record to limit the providers that are allowed to issue a certificate for your domain. You can delete this record all together if you don't want the restriction. More on that here: https://letsencrypt.org/docs/caa/.

And if you need any help with Pages, don't hesitate to use the right forum: https://github.com/orgs/community/discussions/categories/pages.

@yoannchaudet I understand that, but you do have access to github.io 's DNS zone. and it has 3 CAA records:

# dig code-certs.github.io CAA
;; Warning: Message parser reports malformed message packet.

; <<>> DiG 9.16.1-Ubuntu <<>> code-certs.github.io CAA
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 64915
;; flags: qr rd ad; QUERY: 1, ANSWER: 4, AUTHORITY: 0, ADDITIONAL: 0
;; WARNING: recursion requested but not available

;; QUESTION SECTION:
;code-certs.github.io.          IN      CAA

;; ANSWER SECTION:
code-certs.github.io.   0       IN      CAA     0 issue "letsencrypt.org"
code-certs.github.io.   0       IN      CAA     0 issue "digicert.com"
code-certs.github.io.   0       IN      CAA     0 issuewild "digicert.com"
.                       0       IN      OPT

;; Query time: 109 msec
;; SERVER: 172.28.0.1#53(172.28.0.1)
;; WHEN: Sun Feb 05 12:11:52 CST 2023
;; MSG SIZE  rcvd: 169

As you can see, it dose not have a 0 issuewild "letsencrypt.org" record, which prevent me from issue certificates like *.awesome.domain with Let's Encrypt.

Maybe I should change the title to Please add '0 issuewild "letsencrypt.org"' CAA record to github.io

@DevDengChao The CAA record on github.io only apply to github.io and its subdomains. Not to your custom domain.

@yoannchaudet I know it only apply to github.io, but when I set my www.awesome.domain 's CNAME record to awesome-repo.github.io, then the CAA record of www.awesome.domain will be the same as awesome-repo.github.io.That's why the CAA records of github.io could prevent me from issuing certificates.

See: https://sslmate.com/caa/about

I have some different solutions for this issue now:

1. Add a CAA record 0 issuewild "letsencrypt.org" to github.io. This fix the issue directly, but you may need to add another one if someone else is using another CA. 🤔
2. Let the user decide which CAA records should be add to <repo>.github.io This gives us more flexibility, but it will take more time for GitHub to implement this. ⌚
3. Leave GitHub Pages, host your website somewhere else. Keep the CAA records as before, and told the user what will happen when enabling Enforcing HTTPS, let them host their website on other providers if they want more control on CAA records. 🤣

Oh I think now I get it and I have been misreading you the whole time.

I'll check back with the team but I am not sure we want to allow Let's Encrypt to issue wild card certificates on github.io. Transitive or not. I just cannot think of an actual good use case.

In the mean time, since you are getting this requirement via a CNAME, I suggest you use an A record instead. The semantic of it will be better too if you are hosting anything else on subdomains on your side. We will display a warning because this is not the most common scenario but it is allowed.

I am sure you are not doing that but since we are on the topic of wildcard certs, please remember to never point a wildcard DNS record at GitHub Pages. This would expose you to domain takeovers (including with a verified domain).

Confirmed with the team that we don't think we should update our CAA record on github.io. When you delegate a custom domain to GitHub with the use of a CNAME, we take over and we don't provision wildcard certificates on your behalf.

For your specific scenario, I recommend you use an A record.

Thanks for your response, I'll try using A record instead of CNAME record.

Beside, I hope this workaround could be documented in GitHub Pages's docs to help others.

@DevDengChao Thanks again for opening this issue. I hope that all the information above helps 👍

I'll take this feedback to the team, but this seems to be a very specific case. We can't cover every edge case in our documentations, so it may not be included in the end. 💛

I'm going to go ahead and close this issue now. Thank you for your interest in improving the docs! ✨