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
This is a personal website, therefore the backing repository must be named
<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
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
Create new file
index.htmlas name of the file
- Add some random text as content of the file
- Commit the file directly to the
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
Once you have selected the source, your site will be accessible at the address
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
All the steps necessary are explained in great detail in this page of GitHub’s documentation.
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.
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
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
C:\Users\Renato> nslookup renatogolia.com. Non-authoritative answer: Name: renatogolia.com Addresses: 18.104.22.168 22.214.171.124 126.96.36.199 188.8.131.52
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
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.
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
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.
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.
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.