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
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:
Step 2. Custom Domain
To setup a custom domain, you must first configure it at:
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 why.jromero.codes CNAME +nostats +nocomments +nocmd ; <<>> DiG 9.10.6 <<>> why.jromero.codes CNAME +nostats +nocomments +nocmd ;; global options: +cmd ;why.jromero.codes. IN CNAME why.jromero.codes. 1800 IN CNAME jromero.github.io.
Last part is to verify that GitHub is serving your website by double-checking the headers.
$ curl -I http://why.jromero.codes HTTP/2 200 server: GitHub.com ...
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 jromero.codes. CAA 0 issue ";" 0 issuewild "letsencrypt.org" 0 iodef "mailto:firstname.lastname@example.org"
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 jromero.codes CAA +nostats +nocomments +nocmd ; <<>> DiG 9.10.6 <<>> jromero.codes CAA +nostats +nocomments +nocmd ;; global options: +cmd ;jromero.codes. IN CAA jromero.codes. 1799 IN CAA 0 iodef "mailto:email@example.com" jromero.codes. 1799 IN CAA 0 issue ";" jromero.codes. 1799 IN CAA 0 issuewild "letsencrypt.org"
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!
Now, if you ran into any snags, here are a few tips…
View connection handshake
curl -I -v https://why.jromero.codes
View certificate information
echo | openssl s_client -showcerts -servername why.jromero.codes -connect why.jromero.codes:443 2>/dev/null | openssl x509 -inform pem -noout -text