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 ( or you can use your own custom domain ( This guide assumes that your personal domain is

 Steps to set up a website with a  custom domain

  1. Purchase a domain name from your favourite domain name registrar (Google Domains, NameSilo, GoDaddy etc.)
  2. Sign up for GitHub and create a repository on GitHub by clicking the “New repository button” and completing the required details.
  3. 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 
  4. 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
    • In the settings tab on your repository in GitHub, type your custom domain (e.g. and click the “Save” button.
  5. 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 or as shown here. The DNS settings, which should be recorded in your registrar’s A record, are also available here. Create a CNAME record pointing to <username> Some domain name registrars have a GitHub template you can use instead of manually setting everything up.
  6. Optional: set up an alias email using email forwarding with your registrar.

Now you can type in your web browser and this will navigate to the website you uploaded to GitHub!


  1. My website works fine for URLs of the form “” but not for “” A workaround for this is to configure forwarding with your domain name registrar. Simply forward to This is dangerous because it leads to too many redirects which are restricted on most browsers.
  2. I get an error about my CNAME file  Check out the official troubleshooting guide for a range of CNAME errors and solutions.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s