Github Pages is free hosting for static content webpages, and a cost effective way to publish micro-sites for all of your projects. Can it handle custom domains, and HSTS domains? How about multiple custom HSTS domains?
HSTS domains force HTTPS
Every internet connection should be over HTTPS. The Let’s Encrypt project offers free TLS certificates so there is no excuse to use HTTP, and many privacy reasons not to. Every one of your favourite ecommerce websites already force HTTPS, however the most common implementation is to return a 301 Moved Permanently response to any HTTP request directing to the HTTPS url.
But there is a better, formal way to do this called HTTP Strict Transport Security (HSTS). HSTS is an official HTTP mechanism to enforce secure HTTPS connections at the (sub)domain level without 301s.
HTTPS-Only Domains: .dev .app .page
There are many Top Level Domains (TLDs) now, and adoption is growing. The original TLDs are archaic and unhelpful - but simple. Thinking in .com terms is also very US centric, the rest of the world has already moved to country code TLDs like .cn (China) or .de (Germany) to offer better localized (and language) representation.
Outside of regional TLDs, .com is meant to represent a commercial use. Is this the best way to present your site? Tech startups begain to (mis)use the
.io TLD to separate themselves, along with avoiding paying for domain squating.
Out of the +1500 TLDs available, there are 3 common ones:
.page that make HTTPS mandatory using HSTS. That means you cannot serve any traffic over HTTP. These are promoted on Google Domains’ security page https://domains.google/tld/security/ and are likely the precurser to all domains using HSTS.
Github Pages on HTTPS-Only Domains
Short answer, YES you can use HTTPS-Only domains on Github Pages.
The only caveat is that the pages won’t be served until the
Enforce HTTPS checkbox has been successfully enabled.
How Do I Set It Up?
Github pages has good documentation on this, basically to point any subdomain, ie: www.example.com to your Github Pages you will need to create a
CNAME entry at your DNS provider. The
CNAME is an entry in the DNS record that points your
<user>.github.io. It is the DNS equivalent of an HTTP redirect, it is telling browsers requesting
www.example.com to use
Apex Domain Setup
Apex domains are what you purchase when you “buy a domain”. You choose a TLD (Top Level Domain) such as
.eu, and then a unique apex domain in it, such as
example.com. While you may run your website on
api.example.com, it is import to also setup the apex. The only difference is a
CNAME doesn’t work for apex domains, These need a more low level approach; instead of setting up
CNAME to point to another domain you need to use an
A record set to the Github server IP addresses:
No big deal, at your DNS provider, add an
A record of:
18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52
AAAA record (support IPv6) of:
2606:50c0:8000::153 2606:50c0:8001::153 2606:50c0:8002::153 2606:50c0:8003::153
The next step is easy to forget, but very important.
Verify Your Domain with Github
If you don’t verify, ie: prove ownership of of your domain, then there are cases where other users can pretend that they own it and use it for their pages. Should your Github Pages every get disabled the next person to request your domain for their Github Page will get it! This is caused by the limitation that DNS isn’t part of HTTP, it is completely separate.
A record points to
<user>.github.io it is a DNS configuration to resolve your
example.com domain to whatever IP is used by
<user>.github.io, which are the Github Pages server IPs. It then sends an HTTP request for
example.com to one of those Github Pages IPs.
If their Github Pages is set to use your domain as its custom domain their site will be used. Thankfully, stopping this from happening is easy and explained in the documentation. The solution adding a
TXT record in your DNS record with a specific token value that proves you own the domain. This is a common approach used by AWS, Google Adsense, etc.
Don’t Use Wildcard Subdomains
Very similiar how domain hijacking happens above, is if you use
CNAME wildcards, as in pointing
*.example.com to Github Pages. The problem here is that your Github Pages site can only have 1 domain (plus the apex domain) and you are pointing an unlimited number of subdomains to Github Pages. Let’s say you set up your site to be
example.com) but wildcard your
CNAME, this means requests to
blog.example.com also are directed to Github Pages. The first Github Pages site to set their custom domain to
blog.example.com will be served! So don’t use
The flexibility of
CNAME records will create security exploits when misconfigured, but also allows for many use-cases. A common example would be to have a
<user>.github.io site on
www.example.com, plus individual repo sites on
www.example.com/repo2, etc, plus other domains such as
repo3.com pointing to your other repo pages. It’s all done by using the Github Pages UI and setting all