Renato Golia

My name is Renato. I was born in Naples, Italy but I’ve been living in Stockholm, Sweden since 2008. I love working with .NET and AWS and to combine the two together. You can read more about me in the About me section.

Setting up GitHub Pages to host a Jekyll website

5 minute read

In the previous post I mentioned that I decided to use GitHub Pages to host this blog.
In this post, I will explore the setup process on GitHub and also how to configure a custom domain.

Creating the repository

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub.

This is a personal website, therefore the backing repository must be named <user>.github.io, where <user> is your GitHub handler.

Since my handler on GitHub is Kralizek, the backing repository is named kralizek.github.io and its full path is https://github.com/Kralizek/kralizek.github.io.
The repository is private, which is a perk of granted by having a GitHub Pro account.

If your account is on the Free tier, your repository must be public.

Adding a dummy index page

Once created, the repository is empty. Let’s add a dummy index page for now.

To do so, in the homepage of the repository you just created

  1. Click Add file
  2. Select Create new file
  3. Type index.html as name of the file
  4. Add some random text as content of the file
  5. Commit the file directly to the master branch

Enabling GitHub Pages

Now that we have created a repository and added a first page to it, we can enable GitHub Pages.

To do so, go into the settings of the repository and scroll down to the GitHub Pages section.

There you can enable GitHub Pages by selecting the source.

In my case, the site is based on the files available in the root of the master branch.

Once you have selected the source, your site will be accessible at the address https://<user>.github.io.

Configuring a custom domain

Once the site is accessible via the default domain, https://<user>.github.io, it’s time to look at adding a custom domain.

At this step we have to choose if we want to use the apex domain (like in the case of this blog, https://renatogolia.com) or using a subdomain (like www.yoursite.com or blog.yoursite.com).

All the steps necessary are explained in great detail in this page of GitHub’s documentation.

DNS records

The first step is to configure the DNS records so that visitors can be redirected to GitHub Pages.

The setup changes depending on if you are using the apex domain or a subdomain.

Apex domain

If you decided to host your site on your apex domain, you want to configure the DNS records of your domain like the following table

Type Name Value TTL
A @ 185.199.108.153 1 hour
A @ 185.199.109.153 1 hour
A @ 185.199.110.153 1 hour
A @ 185.199.111.153 1 hour
CNAME www @ 1 hour

In words, we’re setting different alternatives for our apex domain (usually represented with a @ sign). The alternatives point to the IP provided by GitHub in their documentation.

You can test the setup by resolving the DNS entry from a console application like nslookup (Windows) and dig (Linux)

C:\Users\Renato> nslookup renatogolia.com.
Non-authoritative answer:
Name:       renatogolia.com
Addresses:  185.199.108.153
            185.199.111.153
            185.199.110.153
            185.199.109.153

The last record is a CNAME record and is used to forward the lookup to the domain specified in the value part of the record. In words, the record on my DNS table can be read as “forward the requests for www.renatogolia.com to renatogolia.com”.
When users navigate to www.renatogolia.com, their browser will receive one of the IP addresses bound to the apex domain. This would normally mean that both www.renatogolia.com and renatogolia.com would return the same content but GitHub has some redirects in place to prevent it.

Watch out! Due to its generic configuration, your domain is exposed for takeover for the whole time GitHub Pages is not configured to consume your domain. To be safe, configure GitHub Pages before setting up the records.

Subdomain

Configuring a subdomain is somehow easier because it requires less records and, most importantly, is a more future-proof approach.

Assuming we are using www as our subdomain, the table of the DNS records will look like this

Type Name Value TTL
CNAME www <user>.github.io 1 hour
CNAME @ www 1 hour

Like for the apex case, the table also contains a record so that users navigating to your apex domain are forwarded to your desired domain.

Since we’re explictly using our GitHub Pages address (ie <user>.github.io), the risk of domain takeover is practically none.

Finally, since the DNS records are not exposed to any concrete IP address, this setup is resilient to any change of IP on GitHub side.

GitHub Pages

Once the DNS records are in place, it’s time to configure GitHub Pages to serve your site on the domain of your choice.

To do so, go into the settings of your repository and specify your domain in the proper textbox. When you press the Save button, GitHub will add a file called CNAME to the root of your repository that contains the specified domain.

Finally, I suggest to enable the Enforce HTTPS option as modern search engines give more emphasis to sites served via HTTPS.

Limits of this solution

As we saw in this post, hosting a site on GitHub Pages is extremely easy and quick. Furthermore, despite being free, your users will not be exposed to any kind of advertisement.

According to GitHub Pages documentation, these are the limitations of the service:

  • The repository’s size should be below 1 GB
  • The website’s size should be no larger than 1 GB
  • The website has a soft bandwitdh limit of 100 GB/month
  • There is a soft limit of 10 builds per hour.

IANAL! Check the guidelines available in the official documentation of GitHub Pages.

Even if the limits seems reasonable, there could be cases where one or more of these limits are exceeded. In this case, there are several strategies to be taken into account.

  • Use an hosting option with less stringent quotas like AWS S3
  • Put a third-party CDN in front of the website
  • Use a third-party build pipeline like Azure DevOps, GitHub Actions, AppVeyor to name few.

Recap

In this post we have created the repository to be used with GitHub Pages, configured it to use a custom domain and made sure that GitHub Pages correctly publishes our (dummy) content.

In the next post we will explore how to configure the GitHub repository to properly accomodate our Jekyll-based website.

Support this blog

If you liked this article, consider supporting this blog by buying me a pizza!

You May Also Enjoy