DEV Community

loading...

Custom domain for GitHub pages

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

Prerequisite

You must be comfortable with GitHub pages if you don't know what they are then please visit the following link
https://docs.github.com/en/github/working-with-github-pages

Intro

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)

settings

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 example.com
  2. Setting up a sub-domain support.example.com

Configure DNS of your apex domain

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

Add four 'A' records that point to Github servers

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

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 plotmarketing.pk

Adding a CNAME record for 'www' subdomain

This step is optional but redirects all the traffic of www.plotmarketing.pk to plotmarketing.pk. This way we can even access the website through the www.plotmarketing.pk 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. .github.io
  4. Now you can visit www.plotmarketing.pk and it will direct you to plotmarketing.pk

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. .github.io
  4. Now you can visit help.example.com which is now linked to your GitHub repo.

sub-domain

Default GitHub pages site in my case aurangzaib-danial.github.io

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 example.com 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 help.example.com they are pointed to our default GitHub domain that directs them to the appropriate Github page.

Github Guide

Discussion (0)

pic
Editor guide