Custom domain for GitHub project pages

by

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.

  1. 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:

enter image description here

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!!

More Related Contents:

  1. How to install an npm package from GitHub directly
  2. Github “Updates were rejected because the remote contains work that you do not have locally.”
  3. Authenticate with GitHub using a token
  4. How to work on personal GitHub repo from office computer whose SSH key is already added to a work related GitHub account?
  5. How to fix HTTP 404 on Github Pages?
  6. GitHub relative link in Markdown file
  7. How to get the current branch within Github Actions?
  8. How to synchronize VSTS and Github respositories when commits are made
  9. How do I center an image in the README.md file on GitHub?
  10. How do I clone a GitHub wiki?
  11. How to link files directly from Github (raw.github.com)
  12. Install specific branch from github using Npm
  13. Jenkins returned status code 128 with github
  14. How do I use an env file with GitHub Actions?
  15. How do you change a repository description on GitHub?
  16. How do I create a folder in a GitHub repository?
  17. How to retrieve the list of all GitHub repositories of a person?
  18. How to escape a pipe char in a code statement in a markdown table?
  19. Github Actions – trigger another action after one action is completed
  20. How to do a fast-forward merge on GitHub?
  21. Setting up a Github Commit RSS feed
  22. Reference GitHub file in jsFiddle
  23. How to release a build artifact asset on GitHub with a script?
  24. Names starting with underscore shows errors Page doesnot exists for gh-pages branch
  25. change github account mac command line
  26. What is this grey git icon?
  27. CocoaPods and GitHub forks
  28. github search limit results
  29. How to run GitHub Actions workflow only if the pushed files are in a specific folder
  30. How do I make a GitHub Action matrix element conditional?

Leave a Comment