はじめに

• GitLab はバージョン 13.0 から hashed storage に対応しており、今までのストレージを legacy storage と呼んで非推奨としている。
• GitLab 13.0 以上で環境を構築してプロジェクトやリポジトリを作成した場合は既に hashed storage になっているのだが、GitLab 12.x.x 以下で環境を構築していてる場合は、当然 legacy storage で動いている。
• GitLab 12.x.x 以下の環境を GitLab 13.0.0〜13.3.x に上げても legacy storage のままで動作してくれるが、そこから GitLab 13.4.0 以上に上げると hashed storage に強制移行させられてしまう。この時、非常に高い確率でプロジェクトのリポジトリが消えてしまうトラブルに遭遇することになる。
• GitLab 14 では legacy storage サポート打ち切りのアナウンスが出ているので、今のうちに hashed storage に移行した方が良い。以下、その手順を示す。
  • 本手順は docker-compose を使って起動している GitLab を前提とする。
    ⇒ 上記のリンク先の解説を試す時は、gitlab-ee を gitlab-ce に置き換えること。

なぜこのナレッジを書いたのか？

• この謎のリポジトリ消失問題を解決するまでに結構な期間悩んでしまったので、「自力で GitLab を動作させている方々のトラブル防止や解決の一助になれば…」と思って書かせていただいた。

移行手順

• ポイント：
  GitLab 13.4.0 以上に上げてしまう前に、GitLab 13.0.0〜13.3.x のどこかの実行環境で legacy storage を hashed storage にマイグレーションしてしまうのがお勧めである。

手順① runner registration tokens の削除

• GitLab 13.0.0〜13.3.x の環境で runner registration tokens を全て削除する。

  docker-compose exec gitlab gitlab-rails dbconsole
  

  -- Clear project tokens
  UPDATE projects SET runners_token = null, runners_token_encrypted = null;
  -- Clear group tokens
  UPDATE namespaces SET runners_token = null, runners_token_encrypted = null;
  -- Clear instance tokens
  UPDATE application_settings SET runners_registration_token_encrypted = null;
  -- Clear runner tokens
  UPDATE ci_runners SET token = null, token_encrypted = null;
  

• これをやっておかないと、後述の gitlab-rake gitlab:storage:migrate_to_hashed の実行の時に hashed_storage:hashed_storage_project_migrate で OpenSSL::Cipher::CipherError: が発生してリポジトリのマイグレーションに失敗する可能性がある。
• もちろん、runner registration tokens を削除せずにマイグレーションに成功すれば御の字である。最初はこの手順①を飛ばしてこの次の手順②から実行し、マイグレーションに失敗したらバックアップを書き戻してここからやり直すのもいいだろう。
• 参考：Reset runner registration tokens

手順② gitlab-rake gitlab:storage:migrate_to_hashed の実行

• 以下のコマンドを実行する。

  docker-compose exec gitlab gitlab-rake gitlab:storage:migrate_to_hashed
  

• このコマンドを実行した後に GitLab の管理者エリアの“監視”→“バックグラウンドジョブ”を開くと、マイグレーションの進行状況やマイグレーション終了時のエラーの有無を確認することができる。
  • マイグレーションが終了した時に OpenSSL::Cipher::CipherError: のエラーが発生していたらマイグレーションに失敗している。このエラーが発生した場合は、バックアップを書き戻してマイグレーションを最初からやり直す時に、最初に手順①を実行して runner registration tokens を削除するとうまくいく。
• このコマンドを実行すると全てのプロジェクトが hashed storage にマイグレーションされる。特定の範囲のプロジェクトをマイグレーションしたい場合は“ID_FROM”と“ID_TO”を追加して以下のようにやればよい。

  docker-compose exec gitlab gitlab-rake gitlab:storage:migrate_to_hashed ID_FROM=50 ID_TO=100
  

• この時指定するプロジェクト ID は、管理者エリアの“概要”→“プロジェクト”→“IDを調べたいプロジェクト”→“Project info:”→“ID:”でわかる。

手順③ hashed storage 移行後のプロジェクト／リポジトリの確認

• legacy storage から hashed storage へのマイグレーションで特にエラーが発生しなかったならば、いくつかのプロジェクトにアクセスしてリポジトリに問題がないことを確認する。

手順④ GitLab 13.0.0〜13.3.x から 13.4.0 以上へのアップグレード

• hashed storage への移行がうまく行ったら、GitLab のバックアップを取った後に 13.4.0 以上にアップグレードする。
• アップグレード後は、いくつかのプロジェクトにアクセスしてリポジトリに問題がないことを忘れないように確認すること。

手順⑤ runner registration tokens の再生成

• 手順①で runner registration tokens を削除してしまった場合は、新しいトークンを作り直す。

まだ GitLab 12.x.x 以下を使っている場合のもっと簡単な移行手順

1. 現在の環境のままで runner registration tokens を削除する。
   • 動作未確認なので 12.x.x 以下ではうまく削除できないかもしれないというリスクがある。
2. GitLab を 13.4.0 以上にバージョンアップする。
3. 削除した runner registration tokens を作り直す。

APPENDIX A：現在利用している GitLab のバージョンの確認方法

• https://GitLabのアドレス/help を開く。
  • 例）https://gitlab.koba.jp/help
• サインインしないと GitLab のバージョンは表示されないので、右上に“Sign in”と表示されていたらサインインすること。

APPENDIX B：参考資料

• Repository storage Rake tasks
• Back up and restore GitLab
• Upgrade to GitLab 13.4.0 (b0481767fe4) killed all repositories