This quick tutorial will describe the process for setting up GitHub Pages with a custom domain and HTTPS enabled.

Step 1. Uploading content

There are various methods to get GitHub Pages published. Using the gh-pages branch keeps the master branch free from the clutter of build artifacts. This works really well for CI as demonstrated on part 2 of this journey.

First step was to create the gh-pages branch and push it:

git checkout -b --orphan gh-pages
git push -u origin gh-pages

To verify github has detected the branch you may check under GitHub Pages at:{USER}/{REPO}/settings

Step 2. Custom Domain

To setup a custom domain, you must first configure it at:{USER}/{REPO}/settings

Then go to your domain registrar and configure a CNAME to your custom domain.

Verify that the CNAME has taken effect. Depending on your DNS server and settings this could take a few hours to propagate.

$ dig CNAME +nostats +nocomments +nocmd

; <<>> DiG 9.10.6 <<>> CNAME +nostats +nocomments +nocmd
;; global options: +cmd

Last part is to verify that GitHub is serving your website by double-checking the headers. Specifically the server: header.

$ curl -I

HTTP/2 200 

Step 3. Enable HTTPS

To enable HTTPS GitHub must be able to issue a certificate for your domain via Let's Encrypt.

With the use of this online tool a set of CAA records can be generated that enables Let's Encrypt to issue certificates.

NOTICE: All the changes are made to the top-level domain and not the subdomain.

The configuration will end up something like this:

Name            Type        Value  CAA         0 issue ";"
                            0 issuewild ""
                            0 iodef ""

Again, you'll go to the domain registrar and configure 3 CAA records to your custom domain.

After applying the changes and waiting for propagation, a quick dig should show your changes:

$ dig CAA +nostats +nocomments +nocmd
; <<>> DiG 9.10.6 <<>> CAA +nostats +nocomments +nocmd
;; global options: +cmd
;                 IN      CAA          1799    IN      CAA     0 iodef ""          1799    IN      CAA     0 issue ";"          1799    IN      CAA     0 issuewild ""

Additionally, you should see an update to the Enforce HTTPS option:

Eventually, this will change to:

You can verify by pulling up your website in chrome and checking the connection:


You should now have a statically hosted site with no storage, traffic, or certificate cost!

Troubleshooting Tips

Now, if you ran into any snags, here are a few tips…

SSL Certificate

View connection handshake
curl -I -v
View certificate information
echo | openssl s_client -showcerts -servername -connect 2>/dev/null | openssl x509 -inform pem -noout -text