How to Use Custom Domains with Github Pages

April 22, 2019


Hosting a project wiki or a personal blog on Github is very easy with github-pages and static site generators like Jekyll. You will end up with a site hosted on <Project/Repository Name>, if you’re happy with that then skip the rest of this article. If you want more or just curious about the steps then keep reading.

What you’ll need

  • Domain hosting
  • Github hosted static site (gh-pages branch)


  1. Setup your domain hosting

    As an example, I am using Godaddy’s admin panel. Your mileage might be different but most domain providers will have similar tools for you to use.

    alt text

    1. Add a A entry to with the following details.

      • Host: @
      • Points to:
      • TTL: 600 seconds

    alt text

    1. Do the same for, and
    2. Add a CNAME with the following details:

      • Host: www
      • Points to:
      • TTL: 1 hour
    3. Save your settings.

    Update: It seems Godaddy has upgraded their interface you need to add those entries and the settings are automatically saved for you.

  2. Setup Github Pages

    1. Switch to your gh-pages branch and create a text file with your domain (e.g. it in the root of your static site.

    alt text

    1. Navigate to Settings > Options > GitHub Pages

    alt text

    1. Point branch to gh-pages branch
    2. Fill in your domain. In my case, it’s
    3. Enable ‘Enforce HTTPS’, if the option is enabled. Sometimes it will indicate you need to wait for 24 hours. Just check again later and enable it if you’re allowed to. If you have a different issue checkout Github article on troubleshooting custom domains.

NPM package

If you’re familiar with npm, you can use gh-pages cli to setup this for you.

npm i -g gh-pages

Before you can deploy to gh-pages. Remember to create the CNAME text file I mentioned earlier in step 1 of Setup Github Pages.

Point it to your static site code, e.g. (dist folder)

gh-pages -d dist 

This will set up your Github pages with the content of your dist folder and point it to whatever domain you specified in CNAME.


If everything went well. You should have your Github hosted site using your shiny new custom domain. :)

By @codespud  
DISCLAIMER This is my personal weblog and learning tool. The content within it is exactly that – personal. The views and opinions expressed on the posts and the comments I make on this Blog represent my own and not those of people, institutions or organisations I am affiliated with unless stated explicitly. My Blog is not affiliated with, neither does it represent the views, position or attitudes of my employer, their clients, or any of their affiliated companies.