Christopher Tobin

Quirk with Custom Domains on User Pages Hosted with GitHub Pages

Christopher Tobin
Christopher Tobin

August 18, 2018

GitHub Pages is a pretty neat feature of GitHub (if you haven’t been able to tell yet I use it to host this website). Overall, I’d have to say my experience has been pretty positive. It has in general been very easy to use. While Jekyll certainly has a learning curve (as all things do), it is definitely manageable.

Unfortunately, my experience when adding a custom domain was not as simple as the docs made it out to be.

The Problem

When creating a personal site, GitHub suggests creating a repository named <username>.github.io. This will allow GitHub to auto-magically configure this repository for GitHub pages.

I created this site in a sevenzerothree.github.io repository, making this a User Page as far as GitHub pages is concerned. This meant it would be hosted at https://sevenzerothree.github.io by default. I eventually grew tired of this, so I decided to add a custom domain to this site. I’ve owned thesevenzerothree.com for several years now but I wasn’t really doing anything with it. This was the perfect opportunity to make it do something useful.

After adding my custom domain in the repository settings and fiddling with DNS settings, my personal site was loading perfectly on https://www.thesevenzerothree.com. All was good right?

Wrong. Very wrong. Adding this custom domain had an unintended side effect: all of my project pages stopped being hosted on sevenzerothree.github.io/{project} and instead were being hosted on thesevenzerothree.com/{project}.

This drove me insane for days. Why was this happening? Did I misconfigure DNS somehow? Did I miss an option to redirect everything to my custom domain? Was this some bug in the GitHub Pages feature?

Like all good developers do, I took to Google to see if someone smarter than me had already encountered this. I came across this issue that added some insight to my problem. As it so happens, this is 100% intentional behavior as far as GitHub Pages is concerned. If you create a User Pages site and use a custom domain, this will affect all of the URLs for any Project Pages sites as well. All of the Project Pages sites will now be hosted on example.com/{project} instead of <username>.github.io/{project}.

This is believe it or not subtly mentioned in the documentation. In the table on that page, it does say that any Project Pages sites will be redirected to the custom domain used on the User Pages site if one exists.

Although this was designed behavior, I still didn’t like it. I wanted to have a custom domain for my personal site, but I didn’t want my project pages hosted on my thesevenzerothree.com domain. I also didn’t want to buy a different domain for my projects. That seemed totally unnecessary. I wanted my project pages hosted at sevenzerothree.github.io/{project}. There had to be a way to do this.

The Solution

The first solution I explored was to create a new Organization specifically for my personal site. The only repository in this Organization would be the one for my personal site. I would hook up my custom domain at this new repository so it would only affect repositories in this new organization. It wouldn’t affect my Personal repositories at all. I could even transfer the repository from my User account to this new Organization account and I wouldn’t lose any history. Sounds pretty straightforward right?

While it would have worked, it presented some compromises that I wasn’t comfortable with:

  • Creating an Organization simply to host a personal website seemed a bit overkill
  • I didn’t like the idea of having my personal site repository separate from my project repositories

In the end, I was making this much more difficult then it needed to be. I was working under the assumption that I had to host this site out of my sevenzerothree.github.io repository.

I didn’t have to do this at all. Project Pages support custom domains just like User Pages do. So the easiest solution was to just rename my repository from sevenzerothree.github.io to thesevenzerothree.com. This converted my repository from a User Page to a Project Page, which means that any custom domain that I add will only affect that Project Page and nothing else. I had to re-add my custom domain on the repository settings but that’s no big deal. I didn’t even have to change any DNS settings!

Even though I made this problem much more of an issue than it needed to be, I’m glad this is fixed. Now my personal site is hosted in my User account just like I wanted it to, and all of my Project Pages are hosted on sevenzerothree.github.io. I consider that a victory.