4 minute read

Categories:
Tags:

GitHub Pages is free hosting for static content webpages, and a cost-effective way to publish microsites 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 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.

Beyond regional TLDs, .com is meant to represent a commercial use. Is this the best way to present your site? Tech startups began to (mis)use the .io TLD to separate themselves, along with avoiding paying for domain squaring.

Out of the +1500 TLDs available, there are 3 common ones: .dev, .app, and .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 precursor 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.

DNS Setup

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 www.example.com to <user>.github.io. It is the DNS equivalent of an HTTP redirect, it is telling browsers requesting www.example.com to use <user>.github.io instead.

GitHub Pages Apex Domain

Apex domains are what you purchase when you “buy a domain”. You choose a TLD (Top Level Domain) such as .com or .eu, and then a unique apex domain in it, such as example.com. While you may run your website on www.example.com and api.example.com, it is import to also set up 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:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

and an 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

If you don’t verify, ie: prove ownership 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.

When your CNAME or 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 similar to how domain hijacking happens, is the exploitation of CNAME wildcards directing *.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 www.example.com ( and 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 CNAME wildcards.

Conclusion

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/repo1, 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 CNAME to <user>.github.io

Categories:
Tags:
Updated:

You May Also Enjoy

Job Queue Execution Management using ZIO Scopes

8 minute read

, ,

Job Queues are critical parts of Enterprise workloads. Complex queues use distributed nodes, state machines, and complex scheduling to trigger and track running jobs. But when simplicity allows the best approach is to create small idempotent jobs. The smaller the unit of work the easier progress can be tracked, jobs can be restarted or rerun with minimal waste, composability and reuse are increased, and logic is easier to reason about. These are the same arguments for Functional Programming and their Effect Systems, such as ZIO. Effect systems are congruent to the enterprise job queue, with ZIO fibers performing work and ZIO Resource Management forming the scheduling and supervision backbone. An efficient job queue can be written using ZIO constructs using surprisingly minimal amount of code. Table of Contents ZIO Resources and Scope Queue Features Class Interface ZIO Concurrency uses Fibers, Not Threads ...

Realtime Client Database using gRPC Bi-Directional Streams and ZIO Hub

1 minute read

, ,

Realtime pushed-based databases such as Google Firebase are a convenient way to ensure clients have the most recent data locally. Data updates are automatically streamed to clients immediately as they happen, or in the case of a client disconnect, immediately after reconnecting. gRPC server streaming and ZIO Hub allow this functionality to be easily replicated and customized beyond what expensive paid-for services such as Firebase can do.

Http4s Streams and Multipart Form-Data File Uploads

10 minute read

, ,

Streaming is the primary mechanism to reduce memory requirements for processing large datasets. The approach is to view only a small window of data at a time, allowing data to stream through in manageable amounts matching the data window size to the amount of RAM available. A practical example is a file-upload, where multi-GBs file streams can be handled by MBs of server RAM. However, enforcing streaming in software code is prone to errors, and misuse or incompatible method implementations will lead to breaking stream semantics, and ultimately to OOM exceptions. This article focuses on streams within the context of file uploads, using the Http4s library for examples.

Compiling Scala Native in a GitHub Action; Alternatives to GraalVM

11 minute read

, ,

Scala Native is a compiler and JDK written in Scala with the goal of removing Scala’s dependency on the JVM. This isn’t meant to achieve a higher performance such as with JDKs, and it is targeting a specialized use-case not considered to be today’s typical Scala development. Its competitors are Rust and Go, not GraalVM, Java or Kotlin. This article goes through common steps and challenges encountered when compiling Scala Native for linux with a GitHub Action.