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: 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 and you control the DNS
  • You own and you control the DNS
  • You have a GitHub account called username
  • You have a repo containing a site at
  • You have a repo containing a site at

Note: I’ve named the repos in the examples to match the domains, but they don’t need to match. Your domain could be 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:
  2. Go to your DNS provider and configure your first domain ( like this:
    1. Create an A record for and enter those IP addresses as individual values for that record.
    2. Create a CNAME record for and enter
      The DNS for should look something like this: DNS settings
    3. Repeat these steps for your second domain (
      The DNS for should look something like this: 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 repo’s Settings > Pages configuration at
    2. Ensure that your branch and path are correct (master and /(root) are probably fine unless you use some other branch name)
    3. Enter for your Custom domain and click save
    4. Now wait….
    5. You can keep trying to refresh your site until it appears at your 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 repo’s Pages settings should now look like this:
      Pages configuration for repo
    8. Repeat this same process for You can use the same steps above, but replace with

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:


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:


Hey, I want


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


Gotcha. Hey GitHub, gimme the site for, por favor.


Let’s see…yep. lives in the repo. Here ya go.


GitHub, dude, thanks! But, while I have you…can I also get, please?


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


I could have told you that. lives in the repo. Render away, Mr. Browser!


You guys rock, GitHub and DNS!


We are well aware of this.


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


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


  • 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.