tutorial

GitHub Pages & Custom Domains

  ·  2 minute read

I love GitHub Pages. So much so that I’ve created several websites using it. This site runs on it, and a few others. 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:

    1. Create the record

      subdomain 10800 IN CNAME name.github.io.

    2. It will use the master branch

    3. Create a CNAME file containing subdomain.website.com

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

    1. Create the records

      @ 10800 IN A 192.30.252.153

      @ 10800 IN A 192.30.252.154

    2. It will use the master branch

    3. Create a CNAME file containing website.com

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

    1. Create the record

      subdomain 10800 IN CNAME name.github.io.

    2. Create a gh-pages branch

    3. Create a CNAME file containing subdomain.website.com

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

    1. Create the records

      @ 10800 IN A 192.30.252.153

      @ 10800 IN A 192.30.252.154

    2. Create a gh-pages branch

    3. Create a CNAME file containing website.com

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

    1. Create the records

      @ 10800 IN A 192.30.252.153

      @ 10800 IN A 192.30.252.154

    2. Create a gh-pages branch

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

    1. Create the record

      subdomain 10800 IN CNAME name.github.io.

    2. 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 :+1:. 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 :star:.

Cheers, Dave

Related Articles