You’re probably familiar with GitHub Pages and how you can host HTML (or Jekyll-generated HTML) as part of your GitHub account. Most of the documentation says that you can host one site per account, but there are some references to hosting multiple sites on a single account. After a bunch of digging and pulling together information from multiple sources, I’m happy to say that it’s possible and actually pretty easy.

GitHub Pages - Single Site

With the standard GitHub pages setup, a user can request a URL (either default GitHub URL or with a vanity domain) and GitHub will map that to your user account’s repository and return the page(s). You can learn more about that setup here: https://pages.github.com/ or About GitHub Pages

This is a visual representation of a single GitHub pages repo responding to a request:

GitHub Pages - Single Site

GitHub Pages - Multiple Sites

What if you want to host multiple GitHub Pages sites from the same user account? There are many resources online that say this isn’t possible, including GitHub (see “GitHub’s Carefully-worded Documentation” below). Some resources talk about using another account (this does work) or configuring an organization for each site (this works as well), but you don’t need to do that.

The following diagram illustrates conceptually how this will work when you have two repos (each containing a site) under a single user account with two different domains mapped to those sites.

GitHub Pages - Multiple Sites

So how do you actually do this?

Setup Multiple GitHub Pages Sites Under a Single User Account

Consider familiarizing yourself with GitHub’s documentation on the topic of GitHub Pages, but if you want to skip all that, I’ll try to cover everything you need to know. You may also want to consult the documentation for About custom domains and GitHub Pages.

Let’s first assume the following for this example:

  • You have two domains, but this works for any number of domains (in theory)
  • You own some-vanity-domain.com and you control the DNS
  • You own other-domain.com and you control the DNS
  • You have a GitHub account called username
  • You have a repo containing a site at github.com/username/some-vanity-domain.com
  • You have a repo containing a site at github.com/username/other-domain.com

Note: I’ve named the repos in the examples to match the domains, but they don’t need to match. Your domain could be some-domain.com and your repo could be named whatever. The naming of the repo is arbitrary.

With those assumptions in place, let’s look at the steps for this configuration:

  1. You’ll need the IP addresses for GitHub’s servers which can be found here. Assuming they haven’t changed since publishing this article, those IPs are: 
    185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
  2. Go to your DNS provider and configure your first domain (some-vanity-domain.com) like this:
    1. Create an A record for some-vanity-domain.com and enter those IP addresses as individual values for that record.
    2. Create a CNAME record for www.some-vanity-domain.com and enter username.github.io.
      The DNS for some-vanity-domain.com should look something like this: some-vanity-domain.com DNS settings
    3. Repeat these steps for your second domain (other-domain.com)
      The DNS for other-domain.com should look something like this: other-domain.com DNS settings
  3. Now that your DNS is configured correctly, it’s time to setup your repos’ Page configuration in GitHub.
    1. Go to your your some-vanity-domain.com repo’s Settings > Pages configuration at https://github.com/username/some-vanity-domain.com/settings/pages
    2. Ensure that your branch and path are correct (master and /(root) are probably fine unless you use some other branch name)
    3. Enter www.some-vanity-domain.com for your Custom domain and click save
    4. Now wait….
    5. You can keep trying to refresh your site until it appears at your www.some-vanity-domain.com URL, but this might take up to an hour or more
    6. Once your site is appearing correctly, you can then check the “Enforce HTTPS” checkbox, but you may have to do this a few times to get it to work while DNS propagates and GitHub creates a certificate for you
    7. Your configuration for your some-vanity-domain.com repo’s Pages settings should now look like this:
      Pages configuration for some-vanity-domain.com repo
    8. Repeat this same process for other-domain.com. You can use the same steps above, but replace some-vanity-domain.com with other-domain.com

But wait, there’s more

Before you do anything else with your local Git repository, make sure you pull (or rebase) from your GitHub remote. Why? As part of this process, GitHub adds a file to your repo in the branch you specified in the Pages configuration. That file is a CNAME text file with the contents being the custom domain you mapped to your GitHub repo. That CNAME file in your repo’s master branch (or whichever branch you specified) will look like this:

www.some-vanity-domain.com

…or…

www.other-domain.com

If you don’t pull/rebase now, you’ll get a merge conflict when you try to push any further changes to GitHub. An alternative, if you forget this step, is to just manually add that file locally, commit it, and then push to GitHub so the file is already there and you don’t get the merge conflict.

How it Works

I’m sure it’s more complex under the covers, but the gist of it is this:

Browser

Hey, I want www.some-vanity-domain.com

DNS

Ah, that’s over at GitHub’s servers.

Browser

Gotcha. Hey GitHub, gimme the site for www.some-vanity-domain.com, por favor.

GitHub

Let’s see…yep. www.some-vanity-domain.com lives in the github.com/username/some-vanity-domain.com repo. Here ya go.

Browser

GitHub, dude, thanks! But, while I have you…can I also get www.other-domain.com, please?

DNS

Hang on, we don’t know that’s at GitHub…wait…it is. Please proceed.

GitHub

I could have told you that. www.other-domain.com lives in the github.com/username/other-domain.com repo. Render away, Mr. Browser!

Browser

You guys rock, GitHub and DNS!

DNS

We are well aware of this.

GitHub

Are we done? I’m kinda busy over here.

Browser

Yeah, all good. Thanks! Later, gatorz!

And now I sit back and wait for the claims of IT heresy and blasphemy to roll into my inbox. ;)

GitHub’s Carefully-worded Documentation

The GitHub documentation for GitHub pages states the following:

You can only create one user or organization site for each account on GitHub. Project sites, whether owned by an organization or a personal account, are unlimited.

This makes it sound like you can only have one site per account, but what I think they are actually saying is this:

You can only create:

  • one user-site

or

  • one organization-site

…for each user account on GitHub.

Project sites, whether owned by an organization or a personal account, are unlimited and the definition of a “project site” is a site that exists within its own repo under the user account.

That is, you can only have one site associated with your user account or organization using the GitHub provided URL, but you can setup multiple sites, each in their own repo, as long as you can setup and manage your own DNS.