In a previous post Hosting a blog using Hugo and Github, I explained how to use Hugo to create a blogging website and host it on Github. In this post we will look at how to configure Github to serve your website using your own domain.

Configure Your Pages Repository

I explained how to organise your Hugo blog/website into two repos; one for the entire website project and the other for the /public folder which represents your website. Let’s call this second repo the “public website” repo.

In order to get Github to serve your website, you need to change the Pages setting of your “public website” repo indicating which branch of your repo is to be published. Usually this will be your master (or main) branch, depending on what you’ve chosen to name your master/main branch as.

Pages setting in Github

After you select the correct branch, make sure you hit the Save button to complete the Pages setup of the repo.

Save Pages setting in Github

After confirming this setting, you should then be able to access your website using the following URL pattern:

http(s)://YOUR_GITHUB_ACCOUNT.github.io/

Github is now serving the entire contents of your “public website” repository as a public website. See Github’s Pages documentation for more information.

Host Under A Custom Domain

If you own your own domain and want to host your Github Pages website under that domain then there are three additional steps that you will need to take.

1. Add a CNAME file to your repo

Create a file within the project repo called CNAME which will contain your domain. If your domain is mydomain.com then the CNAME file at the top level of your Pages repo should contain www.mydomain.com as a single line of text within it.

Your Pages repository structure should look like this:

├── 404.html
├── CNAME
├── about
│   └── index.html
├── assets
│   └── css
│       └── stylesheet.min.f76676363a873676b74674367643ba65.css
├── some-image.png
...

2. Add the domain to the Repo settings

In the Pages setting for your “public website” repository, add the your domain URL in the Custom Domain field

Custom Domain Setting

It’s generally also a good idea to enforce HTTPS (SSL).

3. Configure DNS for your domain

Using your DNS management console, you will need to create the following entries:

  • CNAME entry for www.mydomain.com pointing to your github subdomain (which is based on your Github account name), eg mygithubaccount.github.io
  • Four A entries for the servers that Github uses to host Pages websites

If you do this correctly and query your DNS settings using dig you should see something like this:

$ dig www.mydomain.com +nostats +nocomments +nocmd

; <<>> DiG 9.10.6 <<>> www.mydomain.com dig +nostats +nocomments +nocmd
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 61481
;; flags: qr rd ra; QUERY: 1, ANSWER: 5, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;www.mydomain.com.		IN	A

;; ANSWER SECTION:
www.mydomain.com.	3600	IN	CNAME	mygithubaccount.github.io.
mygithubaccount.github.io. 1665	IN	A	185.199.109.153
mygithubaccount.github.io. 1665	IN	A	185.199.110.153
mygithubaccount.github.io. 1665	IN	A	185.199.111.153
mygithubaccount.github.io. 1665	IN	A	185.199.108.153

After you have made all these changes, be patient and wait for the DNS and Github settings to propagate.

Don’t just assume that you’ve done something wrong if it initially doesn’t appear to be working. I had to wait for around 10 minutes for the changes to first become active but you might have to wait a lot longer depending on the TTL settings for your domain.

Content Theft

When I first configured my “public website” repo as a Pages one, I was surprised to see that the repo had been forked or cloned more than 10 times within a matter of days. To be honest I found this quite surprising and decided that I wanted to block others from being able to reuse my content quite so easily.

The simplest way to do this is to change the visibility of the “public website” repo from Public to Private. However as soon as you do this, Github will no longer host the website for you unless you upgrade your free Github account to a paid one.

So this is what I ended up doing because the resulting hosting charge from Github is still lower than I would pay for any other hosting service with similar capabilities to what Github offers.

Summary

If you’ve successfully followed the steps above, then your Pages repository website will be served by Github under your own domain and you won’t need to manage it in any way at all. Every time you push any changes to your “public website” repo they will appear online within a matter of minutes.

This really is one of the lowest hassle hosting solution for a Hugo website that I can imagine.