はじめに
GitLab Linux Packageではアップグレード前にPre Checkが実行され、アップグレードパスや非互換設定が確認されます。
今回、Self-Managed GitLabをv18.11.7からv19.1.2へアップグレードした際、このPre Checkで Mattermost（GitLab同梱のチャットツール） 関連の非互換設定が検出され、アップグレードが停止しました。
この環境ではMattermostを一度も利用しておらず、gitlab.rbにも有効な設定は存在しませんでした。
しかし、過去に生成された内部設定ファイルにMattermost関連キーが残存しており、それがGitLab v19のPre Checkで検出されていました。
同じ事象に遭遇した方の参考になればと思い、記録として残します。
発生環境は次の通りです。
発生環境
- 形態: Self-Managed GitLab (GitLab Community Edition / Linux Package)
- アップグレードパス: v18.11.7 -> v19.1.2
詳細
GitLab v19でMattermostが削除された
GitLab Linux Packageには、GitLabと連携できるチャットツールであるMattermostが長らく同梱されていました。
しかし、GitLab v19ではLinux PackageにバンドルされていたMattermostが削除され、
従来利用できた mattermost[...] 設定キーはサポート対象外となりました。
そのため、GitLab v19へアップグレードする前に、Mattermost関連の設定を削除しておく必要があります。
発生したエラー
GitLab v19へアップグレードしようとしたところ、Pre Checkで次のようなエラーが表示され、アップグレードが実施できませんでした。
mattermost has been deprecated since 19.0 and was removed in 19.0.
Bundled Mattermost has been removed from the Linux package in 19.0; `mattermost[...]` keys are no longer supported.
Deploy Mattermost separately and point GitLab at it with `gitlab_rails['mattermost_host']`.
See https://docs.gitlab.com/integration/mattermost/#running-gitlab-mattermost-on-its-own-server for setup instructions.
Deprecations found. Please correct them and try again.
dpkg: error processing archive /var/cache/apt/archives/gitlab-ce_19.1.2-ce.0_amd64.deb (--unpack):
new gitlab-ce package pre-installation script subprocess returned error exit status 1
まず /etc/gitlab/gitlab.rb を確認しましたが、Mattermostの有効化設定（mattermost['enable'] = true など）は行っておらず、関連設定はすべてコメントアウトされている状態でした。
原因：/etc/gitlab/gitlab.rb 以外のファイルに残る設定
さらに調査したところ、/etc/gitlab/gitlab.rb以外の以下のファイルにもMattermost設定が存在していることが判明しました。
- /etc/gitlab/gitlab-secrets.json
- /opt/gitlab/embedded/nodes/.json
今回の環境ではMattermostを一度もアクティブにしたことがありませんでしたが、gitlab-secrets.jsonなどにMattermost関連設定が存在していました。この設定がGitLab v19のPre Checkで検出され、エラーを引き起こしていました。
対処方法
以下の3つの手順を実施することにより、Pre Checkを正常に通過できるようになります。
-
/etc/gitlab/gitlab.rbにMattermost関連設定が存在する場合は削除
コメントアウトされていれば基本的には問題ありませんが、念のためmattermost から始まる設定行をすべて削除します。
-
/etc/gitlab/gitlab-secrets.jsonからMattermost関連設定を削除
今回の環境では、/etc/gitlab/gitlab-secrets.json内に残存していたMattermost関連キーが原因だったため、
バックアップ取得後に該当セクションを削除しました。
注意
gitlab-secrets.json はGitLabの暗号化キーを保持する極めて重要なファイルです。
通常、手動編集するファイルではありません。
誤って編集するとデータにアクセスできなくなる可能性があるため、必ず事前にバックアップを取得してください。
# 作業前に必ずバックアップ
sudo cp -p /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak
JSONファイルを開き、以下のような mattermost で始まるセクション（およびその中の記述）を、カンマ（,）の整合性に注意しながら丸ごと削除します。
・・・
},
"mattermost": {
"email_invite_salt": "xxxxxxxxxxxxxxxxx",
"file_public_link_salt": "xxxxxxxxxxxxx",
"sql_at_rest_encrypt_key": "xxxxxxxxxxxxxx",
"register_as_oauth_app": null
},
"postgresql": {
・・・
-
/opt/gitlab/embedded/nodes/<FQDN>.jsonを削除
今回の環境では、このファイルにも古いMattermost関連情報が残っていたため削除しました。
このファイルはChefが管理するnode情報キャッシュであり、次回 gitlab-ctl reconfigure 実行時に再生成されます。
結果
上記の手順を実行した後、再度 apt upgradeを実行したところ、Pre Checkを無事に通過し、
GitLab v19へのアップグレードが正常に完了しました！
まとめ
GitLab v19への移行は、Mattermostを「使っている・使っていない」にかかわらず、
設定ファイル内に自動生成されたデータが残っているだけでアップグレードが阻害されるという罠があります。
もし同様のエラーでアップデートが止まってしまった場合は、
一度 /etc/gitlab/gitlab-secrets.json などの内部ファイルを確認してみてください。
補足
もしMattermostを利用している場合、GitLabとは別環境へStandalone版Mattermostを構築し、環境移行する必要があります。
詳細はMattermost公式ドキュメントを参照してください。（本記事のスコープ外）
Migrating from GitLab Omnibus to Mattermost Standalone