How to host your website on GitHub Pages with a custom domain

If you have a simple website (some Javascript with CSS and HTML) and you’re looking for a place to host it for free, GitHub is not a bad choice. You have the option of hosting without a custom domain (username.github.io/repository) or you can use your own custom domain (example.com). This guide assumes that your personal domain is http://www.example.com.

Steps to set up a website with a custom domain

Sign up for GitHub and create a repository on GitHub by clicking the “New repository button” and completing the required details.

Add your website files to the repository you created (see my Git cheat guide if you’re new to Git). In the repository directory containing the website files type:

git checkout -- orphan gh-pages

git add *

git commit -m "Added website pages"

git push origin gh-pages

To set up the custom domain on GitHub you must:

add a file named CNAME to your repository. This file should only contain one line which is your domain. For example, the line http://www.example.com

In the settings tab on your repository in GitHub, type your custom domain (e.g. example.com) and click the “Save” button.

Let your domain registrar know about the GitHub custom domain by setting up a custom DNS.

Log into your registrar’s settings page and set up a custom DNS pointing to GitHub. The custom IP addresses used by GitHub Pages are 192.30.252.153 or 192.30.252.154 as shown here. Some domain name registrars have a GitHub template you can use instead of manually setting everything up.

Optional: set up an alias email using email forwarding with your registrar. This will allow you to receive

Now you can type http://www.example.com in your web browser and this will navigate to the website you uploaded to GitHub!

Troubleshooting

My website works fine for URLs of the form “example.com” but not for “www.example.com” A workaround for this is to configure forwarding with your domain name registrar. Simply forward http://www.example.com to example.com. This is dangerous because it leads to too many redirects which are restricted on most browsers.

I get an error about my CNAME fileCheck out the official troubleshooting guide for a range of CNAME errors and solutions.