GitHub Pages & custom domains

I love GitHub Pages. So much so that I’ve created several websites using it. What I don’t love is setting up domain records. It’s up there with setting up email accounts and doing the dishes.

The problem

The issue I have with domain records and GitHub Pages is the documentation, it’s not very clear to the average front-end developer like myself (it might just be me though). Also setting up domain records isn’t a regular thing for me, it’s normally done at the start or end of a project that’s taken a few weeks to put together. Which means it doesn’t stay fresh in my mind. So to solve this issue once and for all I’ve created a list of all the ways you can use GitHub Pages and a custom domain.

The options

Using a name.github.io repo with a custom subdomain, e.g. subdomain.website.com:

Create the record

subdomain 10800 IN CNAME name.github.io.

  1. It will use the master branch
  2. Create a CNAME file containing subdomain.website.com

Using a name.github.io repo with a custom naked domain, e.g. website.com:

Create the records

@ 10800 IN A 192.30.252.153

@ 10800 IN A 192.30.252.154

  1. It will use the master branch
  2. Create a CNAME file containing website.com

Using a regular repo with a custom subdomain, e.g. subdomain.website.com:

Create the record

subdomain 10800 IN CNAME name.github.io.

  1. Create a gh-pages branch
  2. Create a CNAME file containing subdomain.website.com

Using a regular repo with a custom naked domain, e.g. website.com:

Create the records

@ 10800 IN A 192.30.252.153

@ 10800 IN A 192.30.252.154

  1. Create a gh-pages branch
  2. Create a CNAME file containing website.com

Using a regular repo with a custom subdirectory, e.g. website.com/repo-name:

Create the records

@ 10800 IN A 192.30.252.153

@ 10800 IN A 192.30.252.154

  1. Create a gh-pages branch

Using a regular repo with a custom subdomain and subdirectory, e.g. subdomain.website.com/repo-name:

Create the record

subdomain 10800 IN CNAME name.github.io.

  1. Create a gh-pages branch

Additional notes

It might be worth checking out this article on understanding DNS, it does quite a nice job of explaining the difference between a CNAME and an A record.

The conclusion

Now that I’ve have this clearly documented I won’t have to guess records every time I come to setting up GitHub Pages 👍. Hopefully this will help you as well. If you know a better way, just submit a pull request to this article. Thanks to @createdbypete and @jdennes for help on getting these right, plus @hdv and @BenjaminReid for proof reading ⭐️.

Cheers, Dave