Skip to content

Troubleshooting HTTPS failure for custom subdomain on GitHub Pages

Jump to bottom Edit New page
Louis Maddox edited this page Oct 12, 2020 · 7 revisions

HTTPS on GitHub Pages for an apex domain

GitHub Pages allows you to set a custom subdomain by either entering it into the web form or (equivalently) modifying the CNAME record.

  • e.g. spin.systems is the custom apex domain from github.com/spin-systems/spin-systems.github.io.

This can be set up simply by adding DNS A records: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153 (see: step 4 of "Configuring an apex domain")

With this, my apex domain spin.systems was automatically set to HTTPS enforcement — GitHub provides SSL certificates through the Certificate Authority [CA] LetsEncrypt, working "out of the box" for the apex domain.

HTTPS on GitHub Pages for a custom subdomain

When I then tried to set this up on my subdomain named conf however, I did not get the same result.

From what I can tell from Twitter, in 2016 GitHub did not use CAA, and by 2018 they did (providing the domain registrar supports managing CAA records).

The CAA record should be entered as follows for my domain provider (GoDaddy):

  • Name: @
  • Flags: 128
  • Tag: issue
  • Value: letsencrypt.org
  • TTL: Custom
    • Seconds: 600 (this is the minimum permitted, i.e. to refresh this record ASAP)

See this guide for more info (specific to GoDaddy).

I probably last tried to set up DNS subdomain records properly in 2016, but didn't manage to get them HTTPS certificated, and probably around 2018 the DNS records I had set up broke entirely (I presume since around this time they switched from suggesting domain forwarding).

Custom subdomains are able to acquire HTTPS certification through CAA records as mentioned above, which I presume will then permit you to use the 'enforce HTTPS' setting in GitHub Pages for the custom subdomain.

Apparently CAA was “a new mechanism” as of 2017 (via). Wikipedia states it was introduced in September 2017.

I am currently waiting for these DNS settings to 'propagate', which I can observe using a DNS lookup utility.

The advice given about wildcard domains appears to implicitly only refer to A records:

Warning: We strongly recommend not using wildcard DNS records, such as *.example.com. A wildcard DNS record will allow anyone to host a GitHub Pages site at one of your subdomains.

This statement only makes sense if interpreted as being about DNS A records. With a DNS CAA record, it means that anyone could... acquire a HTTPS certificate for a subdomain? But then they wouldn't be able to actually set up the redirect for the subdomain without wildcard A records... (I'm pretty certain I have this correct!)

this Q&A mentions:

CAA records are inherited by subdomains - you do not need to publish them under subdomains

Querying DNS records with a DNS lookup utility

The 2 options for DNS lookup on Linux are host and dig. I recommend host for simplicity.

To list all the records for my site I ran:

host -a spin.systems

but oddly, after running this a few times, the output changed and the results omitted the A records for the site. This appeared to be to do with my nameserver, which can be specified simply by adding it after the site whose address is looked up:

host -a spin.systems 8.8.8.8

⇣

Trying "spin.systems"
Using domain server:
Name: 8.8.8.8
Address: 8.8.8.8#53
Aliases:

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 62860
;; flags: qr rd ra; QUERY: 1, ANSWER: 11, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;spin.systems.                  IN      ANY

;; ANSWER SECTION:
spin.systems.           599     IN      A       185.199.108.153
spin.systems.           599     IN      A       185.199.109.153
spin.systems.           599     IN      A       185.199.110.153
spin.systems.           599     IN      A       185.199.111.153
spin.systems.           3599    IN      NS      ns05.domaincontrol.com.
spin.systems.           3599    IN      NS      ns06.domaincontrol.com.
spin.systems.           599     IN      SOA     ns05.domaincontrol.com. dns.jomax.net. 2020101213 28800 7200 604800 600
spin.systems.           3599    IN      MX      10 mailstore1.secureserver.net.
spin.systems.           3599    IN      MX      0 smtp.secureserver.net.
spin.systems.           599     IN      CAA     128 issue "letsencrypt.org"
spin.systems.           599     IN      CAA     128 issuewild "letsencrypt.org"

Received 331 bytes from 8.8.8.8#53 in 53 ms
  • This 8.8.8.8 server address is for Google's nameserver, which is often used (but I don't suggest you pass all traffic through there).

The dig equivalent is more complicated:

dig +nocmd spin.systems any +multiline +noall +answer

To specify the nameserver you prefix it with @:

dig @8.8.8.8 +nocmd spin.systems any +multiline +noall +answer

You can see why I prefer host!

Other links

A news item which mentions that the role of the 'flag bit' (which I had been setting as 0, which is the default value) is to indicate "the directive use is considered critical and must be followed" and gives the example as:

example.org. CAA 128 issue "letsencrypt.org"

This value of 128 being known as the 'critical bit'.

A guide which mentions setting up GitHub Pages site with a CAA record, but querying this site shows the flag bit is set to 0.

Examples here are given of:

example.com. CAA 128 issue "letsencrypt.org"
example.com. CAA 128 issuewild "letsencrypt.org"

Setting up certificates manually

certbot can be used to set up a manual certification for a domain you control, without access to the webserver hosting it.

sudo snap install --classic certbot
sudo certbot certonly --manual --preferred-challenges dns

This in itself does not seem to affect GitHub's checkbox for HTTPS enforcement however (GitHub could in theory check with the CA, LetsEncrypt, for any certificates which could be provided, but it doesn't), and GitHub does not offer you the option to supply a certificate manually (so even though it was generated, it is useless and may as well be deleted).

Not possible to get HTTPS certificates for both apex domain and subdomain for custom domain

The long and short of this thread on the GitHub Community support forum seems to be that it is not possible to generate multiple SSL certificates, and perhaps this affects subdomains which are separately served static sites too.

It is mentioned on this forum thread that GitLab Pages can be used instead of GitHub Pages, and will even mirror a site directly from GitHub.

Main page

Add a custom sidebar
Clone this wiki locally