DEV Community


Custom domain for GitHub pages

aurangzaibdanial profile image Aurangzaib Danial Liaqat Khan Updated on ・3 min read


You must be comfortable with GitHub pages if you don't know what they are then please visit the following link


Recently, my friend asked me to create a static website for his project. I thought about buying hosting for him but then I remembered GitHub pages which is free and also offer custom domain option.

Configure GitHub Repo

  1. Open up the GitHub pages enabled repository on GitHub that you want to configure for custom domain
  2. Open settings for the repository and go to GitHub pages
  3. Enter your custom domain (this creates a new commit that adds a CNAME file at the root of your repo)


My domain provider is Cloudflare. Please apply DNS settings for your domain in your respective provider's web portal.

Please use the appropriate section

  1. Setting up an apex domain
  2. Setting up a sub-domain

Configure DNS of your apex domain

An apex domain is called apex because it is the main the domain i.e. and not

Add four 'A' records that point to Github servers

Adding a record

  1. Select type 'A'
  2. Use @ for the name that implies root of the domain
  3. Add an IP in the ipv4 address
  4. Repeat the above steps until you have four A records

Adding a record

By now we can visit our custom domain that is linked to our repository, in my case

Adding a CNAME record for 'www' subdomain

This step is optional but redirects all the traffic of to This way we can even access the website through the as well.

  1. Select type 'CNAME'
  2. Add the name of the subdomain i.e. 'www'
  3. Target should be your default GitHub pages site i.e.
  4. Now you can visit and it will direct you to

www sub-domain

Configuring DNS for a sub-domain on your existing domain

We have to add a CNAME record for a sub-domain.

  1. Select type 'CNAME'
  2. Add the name of the subdomain e.g. 'help'
  3. Target should be your default GitHub pages site i.e.
  4. Now you can visit which is now linked to your GitHub repo.


Default GitHub pages site in my case

Enforcing HTTPS for our site

In the repository settings on GitHub, there is an option of enforcing HTTPS. That option might not be available for you to enable. If you have followed the above steps correctly then it takes normally 24 hours for this option to work.

Note: if you are using CloudFlare or any other service provider that offers proxy for masking DNS. Do not enable it and keep it plain DNS so GitHub can easily detect if you have setup records correctly. This is vital otherwise you will not able to enforce HTTPS from GitHub

How it all works in theory?

In terms of an apex domain, all the requests received at will be forwarded to GitHub servers. Github will determine which GitHub repository to use depending on the domain name. This is the sole reason why we add a custom domain in the repository section.

In terms of a sub-domain, we have to add a CNAME that is targeted to our default GitHub site because we cannot use IP for CNAME but the domain name. Whenever a user visits they are pointed to our default GitHub domain that directs them to the appropriate Github page.

Github Guide

Discussion (0)

Editor guide