23 Mar 2021

Hugo blog Hosting on GitLab Pages

So you have a Hugo blog and you’re looking for easy hosting? GitHub and GitLab both provide a free static site hosting feature called Pages. Although both work similarly, I’ve chosen GitLab Pages for several reasons and I think it’s the better choice (at the moment).

Why GitLab?

While GitHub Pages (and GitHub in general) is a more popular way to go, it’s not that good. GitLab Pages on the other hand provides more features and uses a relatively simple CI script.

First, GitHub serves your blog from gh-pages branch so you need to write CI script to commit your Hugo output public dir to your repository’s gh-pages branch for it to work. GitLab however serves your blog from CI artifact directly which means you write CI script just to build the Pages and that’s all.

Second, The thing I like more about GitLab Pages is its Pages Settings. Unlike GitHub, you don’t need CNAME file committed in your Hugo site to specify domain/sub-domain. While there’re GitHub Actions that don’t require a CNAME file, you don’t get much control over your domain and SSL certificate settings. GitLab gives you all that with a simple interface under Repository Settings > Pages. GitLab also allows you to specify more than one domain/subdomains.

Last, although your blog source is already kind of public when you publish the blog still there are reasons when you want to keep the blog source private. For any reason, if you want that, GitLab gives you the option to keep your blog source repo private and still be able to serve pages (free of cost).

How?

Create a GitLab repo and push your blog source to it.
Click Settings > Visibility, project features, permissions and enable Pages for everyone.

Create a .gitlab-ci.yml file in your root dir of your repo and paste this in it:

image: registry.gitlab.com/pages/hugo/hugo_extended:latest

variables:
    GIT_SUBMODULE_STRATEGY: recursive

pages:
    script:
        - hugo
    artifacts:
        paths:
        - public
    only:
        - master #default branch of your repo

Now if you don’t have a domain then you can rename the repo to your-gitlab-username.gitlab.io and your blog should be available on https://your-gitlab-username.gitlab.io. But if you have a domain and you want to serve your blog on it then do the following:
- Click on Settings > Pages > New Domain on your repo and enter your domain/sub-domain in there and select Create New Domain. You’ll see text-boxes in front of DNS(CNAME) & Verification status(TXT). These are 2 DNS records you need to add to your domain’s DNS settings(most probably on your domain registrar’s site). Copy both the values somewhere and click Save Changes.
- Open your domain’s DNS settings and add those above 2 DNS records along with one A record pointing to 35.185.44.232 and that’s it. For more info about adding your domain, check the official guide.
For this blog(domain: surendrajat.xyz) I’ve added the following DNS records:
```
 | Key                                | Type | Value                       |
 | ---------------------------------- | ---- | --------------------------- |
 | *                                  | A    | 35.185.44.232               |
 | _gitlab-pages-verification-code... | TXT  | [Verification status value] |
```
For another site(sub-domain: apklab.surendrajat.xyz) I’ve added the following DNS records:
```
 | Key                           | Type  | Value                            |
 | ----------------------------- | ----- | -------------------------------- |
 | *                             | A     | 35.185.44.232                    |
 | apklab.surendrajat.xyz        | CNAME | apklab.gitlab.io [DNS txt value] |
 | _gitlab-pages-verification... | TXT   | [Verification status value]      |
```

And that’s it. There you have it. Your Hugo blog.