Hosting a Hugo website on Gitlab pages

Introduction

In my quest to create a static website for myself I also wanted to find affordable hosting where I could use a custom domain.
Once again, only little research went into finding the right hosting solution, as I found that GitLab offered what I needed for the reasonable price of EUR 0 (That’s only EUR 0 per day!!).

Assumptions

Time to make some assumptions:

You have created a website with Hugo by following my previous post.
Your domain is maintained by GoDaddy.
- If not, then you’re on your own to configure the DNS stuff.

Check out repository

NOTE: Change the folder and username below to match your setup.

Start by checking out the repository and switch to a feature branch where we make changes.

cd ~/Development/
git clone git@gitlab.com:<username>/hugo-site.git
cd hugo-site
git checkout -b feature/gitlab-ci

Create CI configuration file

NOTE: The main branch of my repository is called main, it might be called differently in your repository.

In the root of your repository, create or overwrite a file .gitlab-ci.yml with the following content:

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

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - main

This will make the GitLab CI build and publish your Hugo website every time a push or pull request is completed to the main branch.
Change main to the name of the main branch your repository.

Change base URL for your website

To load assets correctly, Hugo needs to know what the base URL for your website is.

Open the config.toml in the root of your repository and change the baseURL value to match your domain:

baseURL = 'https://hugo.kolbeck.xyz/'

Push changes to GitLab

With the configuration in place to publish the website to GitLab pages, push the changes to the feature branch we created:

git add .
git commit -m "Add GitLab CI configuration"
git push -u origin feature/gitlab-ci

Complete pull request

Since we configured the GitLab CI to only publish the website from the main branch, go to GitLab to create and complete a pull request to get the change merged.

Configure domain

GitLab configuration

Configure GitLab with the domain to be used with your website.
It will give you the values for your DNS configuration to point the domain to the right server and verify that you own the domain:

Open your Hugo project in GitLab.
Go to Settings.
Go to Pages.
Click the ‘New Domain’ button.
Fill in the domain.
- Domain: hugo.kolbeck.xyz
Click the ‘Create New Domain’ button.
Take note of the DNS and Verification status values, which we need to use at GoDaddy.

GoDaddy configuration

NOTE: The root domain (kolbeck.xyz) is removed from the values in GoDaddy DNS configuration.

NOTE: If you use the root domain as the domain for your website, you’ll need to create an A record instead of the CNAME record and have it point the the IP address of the CNAME value.

With the DNS configuration values from GitLab, go to GoDaddy and configure your DNS:

Go to your domain at GoDaddy.
Go to Manage DNS.
Add two new records with the information from GitLab.
(Replace with your values)
- Type: CNAME
  Name: hugo
  Value: kolbeck.gitlab.io
  TTL: 600 seconds
- Type: TXT
  Name: _gitlab-pages-verification-code.hugo
  Value: gitlab-pages-verification-code=ebb3a66ab032880537588fb5f99dca40
  TTL: 1 hour

Make it public

By default, if using a private repository in GitLab, only people with access to the project will be able to access the website.

To change that:

Open your Hugo project in GitLab.
Go to Settings.
Go to General.
Expand ‘Visibility, project features, permissions’.
Change the value for Pages to Everyone.

Send people to your new Hugo website

Now, send people to https://hugo.kolbeck.xyz (well, preferrably your own domain) to see your new website.