Custom domain for GitHub project pages

Question

I have a gh-pages branch in one of my http://github.com repos. The GitHub project pages works fine if I go to http://myuser.github.com/myrepo

I want to setup a custom domain (myexample.com) that will serve up this project pages. I want both myexample.com and www.myexample.com to serve up these project pages.

GitHub pages help says to make an A record and a CNAME record in your DNS. The A record makes sense, but I do not know what CNAME record to make in my DNS.

The gh-pages docs say to make a CNAME record for 'charlie.github.com' which is a user page repository. I do not have a user page repository - I only have a project repository and a gh-pages branch that I want to use for myexample.com and www.myexample.com.

Do I need to make a user page repository just so I can use my project page for www.myexample.com and myexample.com?

I would just try it, but I want to make sure this will work as I already have www.myexample.com live and don't want to make a mistake.

I emailed GitHub support and their response was

You can't have both point to the same gh-pages as far as I know.

I find it hard to believe they would only support A records for project pages.

Has anyone successfully done this before?

Answer 1

1/23/19 UPDATE:

Things have changed quite a bit (for the better) since my last answer. This updated answer will show you how to configure:

1. Root apex (example.com)
2. Sub-domain (www.example.com)
3. HTTPS (optional but strongly encouraged)

In the end, all requests to example.com will be re-directed to https://www.example.com (or http:// if you choose NOT to use HTTPS). I always use www as my final landing. Why(1,2), is for another discussion.

This answer is long but it is not complicated. I was verbose for clarity as the GitHub docs on this topic are not clear or linear.

Step 1: Enable GitHub pages in GitHub settings

1. From your repo, click on the tab
2. Scroll down to the GitHub Pages section. You have two options:
3. Choosing master branch will treat /README.md as your web index.html. Choosing master branch /docs folder will treat /docs/README.md as your web index.html.
4. Choose a theme.
5. Wait a minute while GitHub publishes your site. Verify it works by clicking on the link next to Your site is ready to be published at

Step 2: Specify custom domain in GitHub settings

Enter your custom domain name here and hit save:

This is a subtle, but important step.

• If the custom domain you added to your GitHub Pages site is example.com, then www.example.com will redirect to example.com
• If the custom domain you added to your GitHub Pages site is www.example.com, then example.com will redirect to www.example.com.

As mentioned before, I recommend always landing at www so I entered www.example.com as pictured above.

Step 3: Create DNS entries

In your DNS provider's web console, create four A records and one CNAME.

1. A Records for @ (aka root apex):

Some DNS providers will have you specify @, others (like AWS Route 53) you will leave the sub-domain blank to indicate @. In either case, these are the A records to create:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Check the Github docs to confirm these are the most up-to-date IPs.

2. Create a CNAME record to point www.example.com to YOUR-GITHUB-USERNAME.github.io.

This is the most confusing part.

Note the YOUR-GITHUB-USERNAME NOT the GitHub repo name! The value of YOUR-GITHUB-USERNAME is determined by this chart.

For a User pages site (most likely what you are), CNAME entry will be username.github.io, ex:

For a Organization pages site, CNAME entry will be orgname.github.io, ex:

Step 5: Confirm DNS entries

1. Confirm your A records by running dig +noall +answer example.com. It should return the four 185.x.x.x IP addresses you entered.

2. Confirm your CNAME record by running dig www.example.com +nostats +nocomments +nocmd. It should return a CNAME YOUR-GITHUB-USERNAME.github.io

It may take an hour or so for these DNS entries to resolve/propagate. Once they do, open up your browser to http://example.com and it should re-direct to http://www.example.com

Step 6: SSL (HTTPS) Configuration. Optional, but highly recommended

After you have the custom domain working, go back to the repo settings. If you already have the settings page open, hard refresh the page.

If there is a message under the Enforce HTTPS checkbox, stating that it is still processing you will need to wait. You may also need to hit the save button in the Custom domain section to kick off the Enforce HTTPS processing.

Once processing is completed, it should look like this:

Just click on the Enforce HTTPS checkbox, and point your browser to https://example.com. It should re-direct and open https://www.example.com

THATS IT!

GitHub will automatically keep your HTTPS cert up-to-date AND should handle the apex to www redirect over HTTPS.

Hope this helps!!

...

Old (prior to 1/23/19) answer

So I figured it out. James McLaughlin gave me the nudge I needed.

To Setup a custom domain for a gh-pages Project Pages repo that handles www.yourdomain.com and yourdomain.com (assumes you already have a gh-pages branch on your repo):

1. From your project repo, gh-pages branch. Create a CNAME file with the contents yourdomain.com. Commit then push.

2. In your DNS manager, setup two cname records. One for the root apex (@) and one for www. Both point to YOURusername.github.io. If your DNS provider does NOT support ALIAS records on the root apex (@), simply create A records that point to 192.30.252.153 and 192.30.252.154

3. Wait til your name servers update:

   dig yourdomain.com +nostats +nocomments +nocmd