Tdd Apps Blog

Custom Domain on Github Pages

Sep 8, 2015 5 minute read

Hosting a website in GitHub Pages can be very convenient. However, a subdomain may not be the best name for a website. In spite of being free, this infrastructure is deeply tied to GitHub Pages. If GitHub decides to discontinue GitHub Pages the website cannot be moved elsewhere because all of the outside links will be pointing to a url. A more resilient approach is to use a custom domain. With a custom domain, our hosting provider can be easily replaced while the content can still be accessed from the same urls. The source code is available on GitHub.


Setup CloudFlare

CloudFlare is a service that speeds up websites. It acts as a CDN for static content. CloudFlare also protects against Denial of Service (DDoS) attacks. It can serve a cached version of your website in case it goes down. 2 Follow the next steps to configure your domain with CloudFlare. 3


SSL is an important security feature. In the past few years Internet giants have started a campaing to promote the adoption of SSL through the web. Moreover, SSL is known to increase website rankings on search engines. CloudFlare provides free SSL support.

1- Click Page Rules on the CloudFlare navigation bar.

2- Add a new rule to* to always use https.
Enforce HTTPS

3- Make sure Flexible SSL is selected in the CloudFlare Crypto settings

Configure the DNS

DNS is the system the Internet uses to resolve addresses. A translation tool that given a name ( returns the address where it can be found ( Websites hosted on GitHub Pages must be configured so they can only be found on specific Internet addresses.

Using your DNS configuration tool, create a couple of A records pointing @ to and @ is a shortcut for the domain name. The created A records are configuring to be found at the GitHub Pages servers. DNS changes may take up to a couple of days to reflect.

www subdomain

Many websites were initially known for their www subdomain:,, etc. Nowadays, the www subdomain is not as important as it was initially. However, it is a good practice to keep it working. If somebody types we don’t want to display an error page. Add a CNAME record pointing www to @ to make the website accessible through the www subdomain.
www subdomain

GitHub Pages custom domain setup

Some changes need to be made for GitHub Pages to serve our website with a custom domain.4

1- Create a new GitHub repository and name it after your domain. The repository for this guide will be GitHub displays a code import page once the repository is created.

2- Open a new Command Line window.

3- Clone the repository that was already hosted in GitHub Pages into a new folder. In the following command replace with the clone url from your repository. Also make sure to replace the folder with your domain name.

git clone

4- Open the new folder in the command line.


5- Remove the existing remote for the repository.

git remote remove origin

Git remotes are the mechanism to track were the code is going to go when pushed. 5 The existing remote needs to be deleted so new changes won’t go into the old repository.

6- Add the new remote for the repository. Make sure to replace everything after git remote add origin with the clone url for the new repository.

git remote add origin

From now on, changes to the local repository will be pushed into the newly created GitHub repository.

7- Rename the master branch to gh-pages.

git branch -m master gh-pages

GitHub Pages require custom websites to use a gh-pages branch. Changes that are not in that branch will be ignored.

8- Create a CNAME file. Make sure you replace with your domain name.

echo > CNAME

GitHub Pages require websites with custom domains to have a CNAME file with the associated domain. 6

9- Publish. The source code that resides on GitHub is ultimately what the readers will see. The mechanism to upload our local changes to GitHub is called pushing. The following command can be executed to publish our local changes.

git add -A && git commit -m "publishing" && git push -u origin gh-pages

Success The website is published with a custom domain. It can be accessed through,, and

Site Published

  1. Git Installation 

  2. How Does CloudFlare Work? 

  3. It is not mandatory to have a CloudFlare account. The A and CNAME records can be added to any other DNS configuration tool. 

  4. Setting up a custom domain with GitHub Pages 

  5. Git Basics - Working with Remotes 

  6. Adding a CNAME file to your repository