Hugo のテーマを変えたら GitLab Pages が突然動かなくなった話

このサイトは、Gitlab Pages + Hugoで作られています。
今回、多言語化をしたくて、多言語対応のテーマ Ananke に変えました。
その途中、思わぬところで詰まったので、その記録を残しておきます。

サイトが反映されない

多言語化対応のテーマに変えてから、いつものように Commit → Push をしたのですが、
なぜかサイトに反映されませんでした。

最初は「更新に時間がかかっているのかな？」くらいに思っていたのですが、
いつまで経っても変化がなく、さすがにおかしいと感じました。

AIに相談してみたところ、「Pipeline のログを見てみなよ」と言われ、
サイトを作った時以来ほとんど触っていなかった Pipeline を久しぶりに確認することに。

Pipelineを見てみよう

Error: error building site: render: failed to render pages: render of "/builds/komone/komone.gitlab.io/content/_index.md" failed: "/builds/komone/komone.gitlab.io/themes/ananke/layouts/baseof.html:2:15": execute of template failed: template: home.html:2:15: executing "home.html" at <site>: can't evaluate field Locale in type *langs.Language
Cleaning up project directory and file based variables
00:00
ERROR: Job failed: exit code 1

ログを開いてみると、よくわからないエラーがずらっと。

AIに投げたところ、
「バージョンが古くてレンダリングに失敗してるね」
ということでした。

じゃあバージョンを新しくすればいいじゃない？

どのバージョンを使うかは、「.gitlab-ci.yml」に書いてあります。

image: registry.gitlab.com/pages/hugo:0.121.1

なるほど、この Hugo のバージョンが古いのが原因らしい。
じゃあ新しくすればいいじゃない？ということで、
ローカルで使っている Hugo と同じ hugo:0.164.0 に変えてみました
（※これでは解決しません）

やっぱり出るエラー

Job failed: failed to pull image "registry.gitlab.com/pages/hugo:0.164.0" with specified policies [always]: Error response from daemon: manifest for registry.gitlab.com/pages/hugo:0.164.0 not found: manifest unknown: manifest unknown (manager.go:313:0s)

これはログを読まなくても（読めよ）、直感で分かる。
「ない」んだ。

ちなみに正確には、指定した Hugo の Docker イメージがレジストリに存在していない、というエラーでした。

衝撃の事実

じゃあどのバージョンならあるんだ、と調べていたら、衝撃の事実が発覚。

これまで使われていた GitLab 公式の Hugo コンテナレジストリ
（ registry.gitlab.com/pages/hugo ）が、バージョン 0.140.2 を最後に
停止・非推奨となっていたのです。

というわけで、現在推奨されている代替イメージ「HugoMods」への移行手順と、
その際に遭遇したエラーの解決策をまとめました。（ここからが本題です）

移行手順（.gitlab-ci.yml の書き換え）

Git サブモジュールでテーマを管理しており、Extended 機能（Sass/SCSS など）が不要なシンプルなサイトの場合、以下のように .gitlab-ci.yml を書き換えます。

default:
  image: hugomods/hugo:base

variables:
  HUGO_VERSION: "0.164.0" # 利用したい Hugo のバージョンを指定
  GIT_SUBMODULE_STRATEGY: recursive # サブモジュールを自動取得

pages:
  script:
    - hugo --gc --minify
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

設定のポイント

• イメージの変更
  従来の ://gitlab.com... から hugomods/hugo:base に変更します。
• バージョンの動的指定
  HUGO_VERSION という変数を定義するだけで、
  HugoMods のコンテナが指定したバージョンの Hugo を自動的にダウンロードして実行してくれます。
  今後のバージョンアップが格段に楽になります。

【トラブルシューティング】 manifest unknown エラーの罠

最初、Alpine Linuxベースのイメージを指定しようとしてタグに :base-alpine を指定したところ、以下のようなエラーが発生してしまいました。

ERROR: Job failed: failed to pull image "hugomods/hugo:base-alpine" with specified policies [always]: Error response from daemon: manifest for hugomods/hugo:base-alpine not found: manifest unknown...

原因と解決策
HugoModsのコンテナは標準でAlpine LinuxがベースOSになっているため、
タグ名にわざわざ -alpine を付ける必要はありませんでした。

正しくは hugomods/hugo:base です。
（※Sass/SCSSなどのExtended機能が必要な場合は、 hugomods/hugo:exts を指定します）

この修正を行うことで、無事にGitLab Pagesでのサイトビルドとデプロイが成功するようになりました！

まとめ

GitLab公式のHugoイメージは非推奨となったため、今後はHugoModsへの移行が必須です。
一見面倒に見えますが、一度設定してしまえば HUGO_VERSION を書き換えるだけでいつでも最新のHugo環境が手に入るため、長期的な運用がとても楽になります。
同じエラーでビルドが止まってしまった方の参考になれば幸いです。

• Hugo
• Gitlab Pages
• HugoMods