Issues you might encounter setting up a Hugo Blog on Gitlab

I recently made two changes with this blog:

Hugo is a well documented project and Gitlab’s documentation is quite thorough, but I ran into a few issues of note while relaunching this blog and thought it worth documenting them here to hopefully clear the way for you to more easily set up your own blog.

The first issue I ran into was setting up a custom domain. Verifying ownership was straightforward, but automatic certificate management failed with the following error:

ACTION REQUIRED: Something went wrong while obtaining the Let's Encrypt certificate for GitLab Pages domain 'eyeofthesquid.com'

This meant something was wrong with the advanced DNS settings on my domain name registrar. Gitlab’s documentation makes clear two out of the three setting needed for a custom domain. The missing piece is the host. This should be set to @ for your TXT and A records as shown below.

Advanced DNS Setup

One of the key differences between Github and Gitlab posting is where the static site is generated. On Github, you generate the artifacts locally and push them to Github. Gitlab, on the other hand, builds your site as part of a CI/CD pipeline and publishes to the Pages server. My initial attempts to deploy were met with the following cryptic error: pages:deploy - missing pages artifacts. Fortunately OCT8L had me covered with this post. For reasons still unclear, Hugo cannot build directly to the public folder for a successful Gitlab deploy. Instead, the workaround is to build to some other folder and rename it public, as shown here.

pages:
  script:
  - mkdir .public
  - hugo -d .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master

With this change, a completely unstyled version of my blog deployed successfully. Links to posts used the default domain (ryanpmoser.gitlab.io) instead of eyeofthesquid.com. After some experimentation, I resolved these issue with a couple of changes to the config.toml file.

baseURL = "/" # changed this line
languageCode = "en-us"
title = "Hi. I'm Ryan Moser."
theme = "soho"
relativeURLs = true # added this line

The example Hugo configuration works for a single domain; this is the only solution I found that works for multiple domains.

All in all, I am quite happy with this setup. I was able to resolve these issues quickly in part because Hugo and Gitlab are both so performant. When I tested changes to resolve the issues described above, new versions of the blog went live seconds after I pushed.