Hugo on PHP Boy Scout

The build gate these sites never had

Mon, 06 Jul 2026 00:00:00 +0000

I run three Hugo sites now. This blog, my dad’s B&B, and the vanlife site my wife and I are slowly putting together. All three build with Hugo and deploy to GitLab Pages, and until recently all three had the same blind spot: the build only ever ran on main.

Which means that if I pushed something that broke the build, a typo in a shortcode, a cross-link to a page that doesn’t exist, a theme bump that didn’t take, I found out after it landed. The change was already merged, sitting on the default branch, and the deploy was the thing that fell over. No gate, no warning, nothing telling me on the merge request that the site wouldn’t build. Just a red pipeline on main and a site that had just stopped updating.

Three copies of the same job

I’ve written before about pulling shared CI into components you include rather than copy-paste, and this was a textbook case of why. Each of the three sites had its own hand-rolled pages job: the same pinned hugomods/hugo image, the same GIT_DEPTH: 0, the same nightly rebuild, all written out three times and drifting apart a little more with every tweak. I already had a zensical-pages component for the docs framework I use elsewhere, but nothing covered a plain Hugo build.

So I wrote one: a hugo-pages component in my shared cicd project, and pointed all three sites at it.

The gate they were missing

The interesting part isn’t the deduplication, it’s what the component fixes. It splits the work into two jobs, and that split is the entire reason the component exists.

hugo-build builds the site to public/, and it carries an explicit rule so it runs in merge-request pipelines too:

rules:
 - if: '$CI_COMMIT_TAG'
 when: never
 - if: '"$[[ inputs.mr_gate ]]" == "true"'
 when: on_success

That second line is the bit the old jobs never had. Push a broken Hugo build now and it shows up red on the merge request, where you can see it before merging, instead of sailing onto main and leaving the deploy as the only thing left to fall over. It’s interruptible: true, so pushing a fix cancels the in-flight run rather than queuing behind it. The deploy is a separate job, pages, which only runs where it should:

pages:
 variables:
 GIT_STRATEGY: none
 rules:
 - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
 when: never
 - if: '$CI_COMMIT_BRANCH == "$[[ inputs.deploy_branch ]]"'
 - if: '$CI_PIPELINE_SOURCE == "schedule"'

It takes the artifact hugo-build already produced and republishes it, with GIT_STRATEGY: none because there’s nothing to clone. Build everywhere, catch the breakage early; deploy only from main (and one other place, which is where it gets interesting). The component is pinned at v0.13.0.

The one component that wants to run on a schedule

Here’s the bit I like. Every other component in my cicd project carries a leading guard that says never run on a schedule, because a nightly Renovate schedule firing a release job or a deploy is exactly the kind of pointless busywork you don’t want.

hugo-pages does the opposite, on purpose. It deploys on schedule, and the reason is sitting in plain sight in the component itself:

# Schedule note: unlike every other component (which carries a
# `schedule → never` guard ...), hugo-pages DELIBERATELY deploys on
# `schedule`. A nightly pipeline schedule is the mechanism by which
# future-dated, non-draft posts go live once their date arrives (Hugo
# excludes future-dated content from `production` builds until then).
# The schedule IS the feature.

When I write a post and date it next Tuesday, Hugo’s production build simply doesn’t include it yet, because its date is in the future. Nothing publishes it on the day except a build that runs on the day and finds that the date has now arrived. That’s the nightly schedule. It’s not noise to be guarded against here, it’s the publish button. The post you’re reading went live exactly this way: written days early, dated forward, and pushed out by a scheduled pipeline the morning its date came up.

One codebase, two flatly opposite rules about the same trigger, and knowing which site wants which is the actual design.

A gate you can switch off

There was one wrinkle. The new MR build gate is the right default for a docs site with contributors, but for these three blogs it was friction. I run them trunk-based: I work on main, I audit locally, I push. A mandatory merge-request build for a workflow that doesn’t really use merge requests is a job that mostly just sits there.

So the gate is a boolean you can turn off:

mr_gate:
 type: boolean
 default: true

Left at its default, hugo-build runs everywhere and the gate is on, which is the safe posture for anyone adopting the component fresh. Set it to false, as this blog does, and hugo-build falls through to running only where it deploys, matching the classic Pages-only-on-main setup the sites had before, but now without three copies of the YAML to maintain. Safe by default, loose by choice, and the choice is one line.

Where it leaves things

A reusable component instead of three drifting copies, a build gate that catches a broken site before it merges, a schedule that publishes tomorrow’s post on time rather than firing for nothing, and an opt-out for the trunk-based sites that don’t want the gate. None of it is clever. It just means the next time I fat-finger a shortcode, I find out on the merge request and not from my dad asking why the B&B site is showing a stack trace.

Moving this blog off Jekyll

Thu, 21 May 2026 00:00:00 +0000

The blog you’re reading used to be a Jekyll site on GitHub Pages, built on the lovely beautiful-jekyll theme. It isn’t any more: it’s Hugo now, published to GitLab Pages. The hosting move rode along with go-tool-base leaving GitHub for GitLab, but dropping Jekyll for Hugo was its own decision, and the more interesting one. Most of the migration was painless. Two bits were not, and they’re the two bits worth writing down.

Why leave Jekyll

Jekyll hadn’t done anything wrong, exactly. beautiful-jekyll is a genuinely nice theme and the site worked fine for years. But it had started to show its age. It hadn’t seen much improvement in a long while, and keeping it building meant staying on older versions of Ruby. Ruby is a perfectly good language, just never one I’ve much enjoyed living in, and I could feel one of those fork-it-and-drag-it-up-to-date afternoons coming, the kind I’d done before and didn’t fancy repeating.

So rather than patch up what I had, I asked the more interesting question: what else is out there? It came down to a shortlist of two, Astro and Hugo. Hugo won, fairly narrowly. Partly I just liked more of its out-of-the-box themes. And partly because it’s written in Go: one portable binary, no toolchain to wrangle, the sort of thing an engineer can drop onto any machine and run without a second thought.

The day every image on the blog tripled

The first proper snag was about where images live. Hugo would happily have let me keep Jekyll’s arrangement, one big /assets/images/ folder with every post linking into it by absolute path. But I’d picked the Stack theme, and Stack leans towards page bundles: each post is a directory, and the post’s own images sit right next to its index.md, referenced by plain relative name. The cover image becomes a resource of the post rather than a file in a shared bucket.

That’s a better model, and I decided to commit to it. Getting there, I managed to make a proper mess. The migration copied the old assets/images across, and Hugo’s static/ directory wanted a copy too, and then I started moving covers into the bundles, and at one humbling point a count turned up every image existing three times: once in assets/images, once under static/, and once in a bundle. A blog with a hundred-odd images had become a blog with three hundred-odd, most of them duplicates nobody referenced.

The fix was to go all the way to the bundle model: move each post’s images into its own directory, rewrite the references from absolute /assets/images/x.png paths to bare x.png, and delete the two shared piles entirely. Once the images lived with the posts, there was exactly one copy of each and the path was obvious. But for an afternoon the repository was a hall of mirrors, and the lesson was to pick the new tool’s model and go all the way to it, rather than carrying the old one alongside it and ending up with both.

The “extended” image that wasn’t new enough

The second one cost me the most time, and it’s the most transferable, so it gets the most words.

Hugo comes in two flavours, ordinary and extended, and the Stack theme needs extended because it compiles SCSS. So I reached for an off-the-shelf extended Hugo container image, wired it into the pipeline, and watched the build fail with an error about a template function the theme was calling that simply didn’t seem to exist.

I spent far too long suspecting the theme, my config, my content. The actual culprit was a version. The image I’d grabbed was a couple of minor releases behind, and Stack v4 uses .Site.Language.Locale, a Hugo feature that only landed in 0.157. The image was older than that, so the function genuinely wasn’t there, and the error was telling me the literal truth in a way I wasn’t ready to hear. “Extended” had told me the flavour was right and lulled me into not checking the version, which was the thing that actually mattered.

The fix was to pin a specific, recent extended image rather than trusting a floating “extended” tag to be new enough. The pipeline now runs on a pinned hugomods/hugo:debian-git-0.161.1, comfortably past the 0.157 the theme needs, and the build that had been failing on a missing function went green the moment the version was right. A theme has a minimum Hugo version the same way any dependency has a minimum, and “extended” is a feature flag, not a version number.

What it comes down to

Moving this blog from Jekyll to Hugo, and from GitHub Pages to GitLab Pages on the way, was mostly a pleasant afternoon, with two frustrations worth sharing. Commit fully to your theme’s page-bundle model rather than dragging Jekyll’s shared-assets layout along beside it, or you’ll briefly own three copies of every image. And pin your Hugo version explicitly, because a theme needs a recent enough Hugo, and the “extended” label tells you nothing at all about whether yours is.

If the site renders for you now, both got sorted. If it doesn’t, well, you’re reading this in a text editor, and I’ve some more debugging to do.