The job described in title can be divided into several steps:

  • Follow GitLab Pages Documentation to create your GitLab Pages at username.gitlab.io
  • Buy your favorite custom domain
  • [Optional] Transfer your domain resolving to DNSPod in case of domain being blocked by GFW
  • Associate your domain to GitLab Pages
  • Enable SSL/TLS connection via Let’s Encrypt

I am not writing long to guide you step by step, because GitLab Pages Documentation is a very good guide for us to go through the above steps.

I just guide you two things that are not covered in official docs:

  • Transfer DNS Resolving
  • How to integrate Let’s Encrypt to Hugo

Why Need DNS Resolving Transfer

This domain, zpj.io for example, is registered from GoDaddy.com. However, China GFW blocks the naming servers of GoDaddy. As a consequence, my domain cannot be resolved within GFW.

Here is a thing, you may or may not know: The DNS naming server and domain register are basically two independent things. It is quite common that, you register you domain from one site, and resolve the domain by different naming service.

So, back to GoDaddy being blocked by GFW case, the solution is straightforward: resolve the domain by DNS naming servers within GFW. In my case, it is DNSPod.cn. It provides free DNS resolving service in China. Moreover its security and platform availability are trustworthy, because DNSPod now a product of Tencent.

How to Transfer ?

  1. sign-up/in your DNSPod.cn account, and add your domain to the control panel.
  2. Immediately after adding your domain, you may be warned that the naming server is not pointing to DNSPod.cn.
  3. Don’t worry. Now go to GoDaddy control panel, change the naming servers to fp1dns1.dnspod.net and fp1dns2.dnspod.net.
  4. Wait 1 minute or 2, reload the GoDaddy control panel, and you may see that the naming servers have switched to DNSPod ones.
  5. Back to DNSPod control panel, now add a DNS CNAME record like @ CNAME USERNAME.gitlab.io. This CNAME record will redirect the domain to your USERNAME.gitlab.io.
  6. Go to your USERNAME.gitlab.io project, open Settings->Pages, click “New Domain” and add your domain here.
  7. Since the recent update, GitLab Pages requires verifying your control over the domain. The strategy is to add a secret DNS TXT record to your domain. Similar to Step 5, add the DNS TXT record.
  8. Several minutes later, the verification shall be passed, and your custom domain is now officially up!

Integrate Let’s Encrypt to Hugo

Follow the most part of the tutorial Securing your GitLab Pages with TLS and Let’s Encrypt to setup HTTPS for your domain. However, when dealing with Let’s Encrypt verification string, the tutorial is not working if you use Hugo static site generator.

The problem is about the URL. The URL segment leading to Let’s Encrypt verification string starts with a dot “.”. Jekyll based approach use a post with a fixed URL to support this. However, the post managed by Hugo does not support “.” started URL.

After some googling, I find the solution, which is much easier than in Jekyll. The solution is: create a directory hierarchy identical to the Let’s Encrypt verification URL in <site-Repo/static> directory, then Hugo will directly map this path to your site. In this way, Let’s Encrypt verification URL is available.