While poking around my Tugboat Dashboard, I noticed the base preview for the main branch in this repo had failed. The site was still working, and it wasn’t until today that I needed to get pull request previews up and running again for this repo. The error was a bit cryptic at first glance, but it turned out to be a straightforward version mismatch with a less-than-straightforward paper trail.

I used Claude Code in VS Code to help me diagnose and fix the error, and we worked together to devise a plan to update the update-theme workflow and Tugboat to be more resilient to automatic changes and to put me—the human—in the loop when needed. Claude Code helped me write a detailed PR description and turn this incident into a blog post, which I edited and added to. Robot teamwork!

The error

1
2
3
4

WARN  Module "github.com/CaiJimmy/hugo-theme-stack/v4" is not compatible
      with this Hugo version: Min 0.157.0 extended
ERROR error building site: ... at <reflect>: can't evaluate field
      IsImageResourceWithMeta in type interface {}

Two errors, one cause. The theme (hugo-theme-stack) had been auto-updated to a version that requires Hugo 0.157.0 extended as a minimum. My Tugboat config was pinned to Hugo 0.155.3. The IsImageResourceWithMeta template error isn’t a separate bug—it’s what happens when the theme tries to use a field that doesn’t exist in the older Hugo version.

How did this happen?

This site’s repo includes a GitHub Actions workflow, .github/workflows/update-theme.yml, that runs on a daily cron schedule:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

- name: Update theme
  run: hugo mod get -u

- name: Tidy go.mod, go.sum
  run: hugo mod tidy

- name: Commit changes
  uses: stefanzweifel/git-auto-commit-action@v5
  with:
    commit_message: 'CI: Update theme'

That workflow installs hugo-version: 'latest' and then runs hugo mod get -u, which pulls the latest version of the theme and commits the result directly to main. No build validation, no review step. When the theme bumped its minimum Hugo requirement, the workflow committed the update anyway, the main branch now had an incompatible theme version, and Tugboat’s next preview build failed.

The version mismatch lived in two different config files that had no awareness of each other:

The immediate fix

The quickest fix was updating .tugboat/config.yml to install a Hugo version that satisfies the theme’s requirements. Hugo 0.161.1 is the current latest release, so I bumped the download URL there:

1
2
3
4
5

# Before
- curl -Ls https://github.com/gohugoio/hugo/releases/download/v0.155.3/hugo_extended_0.155.3_Linux-64bit.tar.gz | tar -C /usr/local/bin -zxf - hugo

# After
- curl -Ls https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_extended_0.161.1_Linux-64bit.tar.gz | tar -C /usr/local/bin -zxf - hugo

That unblocks Tugboat, but it doesn’t prevent the same thing from happening the next time the theme bumps its minimum Hugo requirement. I needed to rethink the workflow.

Making it future-proof

The core problem is that the workflow had no feedback loop: it updated the theme, assumed everything was fine, and committed. I made three changes to address that.

1. Auto-sync the Tugboat Hugo version (automated)

The workflow already installs the latest Hugo to run hugo mod get -u. After updating the theme, I extract that version number and rewrite the download URL in .tugboat/config.yml to match:

1
2
3
4

- name: Sync Hugo version in Tugboat config
  run: |
    HUGO_VERSION=$(hugo version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
    sed -i -E "s|/download/v[0-9.]+/hugo_extended_[0-9.]+_Linux-64bit|/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit|g" .tugboat/config.yml

Now the workflow keeps both environments in lock-step automatically. Whatever Hugo version the workflow installs and validates against is the same version Tugboat gets in the same commit.

2. Build validation (automated)

After updating the theme and syncing the Tugboat config, the workflow now tries to actually build the site:

1
2

- name: Build site
  run: hugo --gc --minify

If the build fails—bad template, incompatible theme change, anything—the workflow stops here. Nothing gets committed. This is the automated gate: it catches functional breakage before it touches the repo.

3. Open a PR instead of pushing directly to main (human in the loop)

Even if the build succeeds, hugo mod get -u is pulling in external code and committing it automatically. A theme update that builds cleanly could still introduce changes worth reviewing—a new JavaScript dependency, a layout change, a modified partial. The original workflow gave no opportunity to see any of that.

I replaced the auto-commit action with peter-evans/create-pull-request, which opens a PR on a branch (automated/update-theme) instead of pushing to main:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

- name: Create Pull Request
  uses: peter-evans/create-pull-request@v7
  with:
    commit-message: 'CI: Update theme'
    title: 'CI: Update theme'
    body: |
      Automated theme update via `hugo mod get -u`. Please review changes before merging.
    branch: automated/update-theme
    delete-branch: true
    add-paths: |
      go.mod
      go.sum
      .tugboat/config.yml

A few details worth calling out:

• add-paths scopes the PR to only the three files that should change. The build step generates output in public/, which we don’t want to commit.
• delete-branch: true cleans up the branch after the PR merges.
• If the theme is already up to date, there are no changes to the specified paths and no PR is opened. No noise on quiet days.
• pull-requests: write was added to the job permissions to allow the action to open PRs.

The updated workflow

Here’s the full workflow after these changes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

name: Update theme

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  update-theme:
    runs-on: ubuntu-latest

    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true

      - name: Update theme
        run: hugo mod get -u

      - name: Tidy go.mod, go.sum
        run: hugo mod tidy

      - name: Sync Hugo version in Tugboat config
        run: |
          HUGO_VERSION=$(hugo version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
          sed -i -E "s|/download/v[0-9.]+/hugo_extended_[0-9.]+_Linux-64bit|/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit|g" .tugboat/config.yml

      - name: Build site
        run: hugo --gc --minify

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v7
        with:
          commit-message: 'CI: Update theme'
          title: 'CI: Update theme'
          body: |
            Automated theme update via `hugo mod get -u`. Please review changes before merging.
          branch: automated/update-theme
          delete-branch: true
          add-paths: |
            go.mod
            go.sum
            .tugboat/config.yml

Takeaways

Automation that commits directly to your main branch with no validation is convenient right up until it isn’t. The combination that works better here is:

• Automated gates to catch objective failures (the build doesn’t compile, the version numbers are out of sync)
• Human review for everything that passes the automated gate but still involves external code landing in your repo

Neither one alone is enough. The build gate would have caught the broken template error in this case—but a future theme update that builds cleanly and introduces something undesirable would still slip through without the PR step. And the PR step alone, without the build gate, would still surface broken builds in review instead of catching them before the PR is even opened.

Layers are good.