GitLab パッケージを使って GitLab をアップグレードします。

GitLabパッケージを使うことで、GitLabを新しいバージョンにアップグレードすることができます。

前提条件

  • サポートされているアップグレードパスを参照して、アップグレードのタイミングを決定してください。メジャーバージョンを直接スキップすることはできません(たとえば、10.3から12.7へワンステップで移行する)。
  • 非パッケージインストールから GitLab パッケージインストールにアップグレードする場合は、非パッケージインストールから GitLab パッケージインストールへのアップグレードをご覧ください。
  • バックグラウンドマイグレーションが完全に完了していることを確認してください。バックグラウンドマイグレーションが完了する前にアップグレードすると、データが破損する可能性があります。バックグラウンドマイグレーションが完了するまでの時間を考慮して、メジャーリリースとマイナーリリースの間のアップグレードは週に1回までとすることをお勧めします。
  • Gitalyサーバーは、アプリケーションサーバーをアップグレードする前に、新しいバージョンにアップグレードする必要があります。これにより、アプリケーション・サーバー上のgRPCクライアントが、古いGitalyのバージョンがサポートしていないRPCを送信することを防ぎます。

ダウンタイム

  • シングルノードインストールの場合、アップグレード中はユーザーが GitLab を利用できません。ユーザーのウェブブラウザにはDeploy in progress メッセージか502 エラーが表示されます。
  • 複数ノードのインストールについては、ゼロダウンタイムアップグレードの実行方法をご覧ください。
  • マルチノードインストールへのアップグレードもダウンタイムで実行できます。

バージョン固有の変更

バージョンのアップグレードには手動操作が必要な場合があります。詳細については、アップグレード先のバージョンを確認してください:

以前のGitLabバージョン

GitLabの以前のバージョンのバージョン固有の情報については、ドキュメントアーカイブをご覧ください。アーカイブにあるドキュメントのバージョンは、さらに以前のバージョンのGitLabのバージョン固有の情報を含んでいます。

例えば、GitLab 15.11のドキュメントには、GitLab 11までのバージョンの情報が含まれています。

アップグレード前のバックアップ

新しいGitLabバージョンをインストールする前に、GitLabデータベースはバックアップされます。/etc/gitlab/skip-auto-backup に空のファイルを作成することで、この自動データベースバックアップをスキップすることができます:

sudo touch /etc/gitlab/skip-auto-backup

とはいえ、自分自身で完全な最新バックアップをメンテナーすることを強くお勧めします。

公式リポジトリを使ったアップグレード

すべてのGitLabパッケージはGitLabパッケージサーバーに投稿されます。5つのリポジトリがメンテナーされています:

GitLabCommunity EditionまたはEnterprise Editionをインストールしたのであれば、GitLabの公式リポジトリはすでにセットアップされているはずです。

公式リポジトリを使って最新バージョンにアップグレードしましょう。

GitLab を月に一度など定期的にアップグレードする場合は、パッケージマネージャを使って最新バージョンにアップグレードできます。

GitLabを最新バージョンにアップグレードするには:

# Ubuntu/Debian
sudo apt update && sudo apt install gitlab-ee

# RHEL/CentOS 6 and 7
sudo yum install gitlab-ee

# RHEL/CentOS 8
sudo dnf install gitlab-ee

# SUSE
sudo zypper install gitlab-ee
note
GitLab Community Editionの場合は、gitlab-eegitlab-ceに置き換えてください。

公式リポジトリを使って特定のバージョンにアップグレードするには

Linuxのパッケージマネージャは、インストールやアップグレードの際に利用可能な最新バージョンのパッケージをインストールするのがデフォルトです。最新のメジャーバージョンに直接アップグレードすることは、複数ステージのアップグレードパスを必要とする古いGitLabバージョンにとって問題となることがあります。アップグレードパスは複数のバージョンにまたがることがあるので、アップグレードのたびに特定の GitLab パッケージを指定する必要があります。

パッケージマネージャのインストールやアップグレードコマンドで、意図するGitLabのバージョン番号を指定するには:

  1. インストールするパッケージのバージョン番号を確認します:

    # Ubuntu/Debian
    sudo apt-cache madison gitlab-ee
       
    # RHEL/CentOS 6 and 7
    yum --showduplicates list gitlab-ee
       
    # RHEL/CentOS 8
    dnf --showduplicates list gitlab-ee
       
    # SUSE
    zypper search -s gitlab-ee
    
  2. 以下のコマンドのいずれかを使用して、特定のgitlab-ee パッケージをインストールし、<version> をインストールしたい次のサポートされているバージョンに置き換えてください (インストールするバージョンがサポートされているパスの一部であることを確認するため、アップグレードパスをレビューしてください):

    # Ubuntu/Debian
    sudo apt install gitlab-ee=<version>
       
    # RHEL/CentOS 6 and 7
    yum install gitlab-ee-<version>
       
    # RHEL/CentOS 8
    dnf install gitlab-ee-<version>
       
    # SUSE
    zypper install gitlab-ee=<version>
    
note
GitLab Community Editionの場合は、gitlab-eegitlab-ceに置き換えてください。

手動でダウンロードしたパッケージを使用したアップグレード

note
手動インストールよりもパッケージリポジトリの利用をお勧めします。

何らかの理由で公式リポジトリを使わない場合は、パッケージをダウンロードして手動でインストールしてください。この方法は、GitLabを初めてインストールするときにも、アップグレードするときにも使えます。

GitLabをダウンロードしてインストールするには:

  1. パッケージの公式リポジトリにアクセスします。
  2. インストールしたいバージョン(例えば 14.1.8)を検索してリストを絞り込みます。1つのバージョンに複数のパッケージが存在することがあり、サポートされているディストリビューションやアーキテクチャごとに1つずつ存在します。ファイル名の隣にはディストリビューションを示すラベルがあります。
  3. インストールしたいパッケージのバージョンを探し、リストからファイル名を選択してください。
  4. 右上の「ダウンロード」を選択します。
  5. パッケージのダウンロードが完了したら、以下のいずれかのコマンドを使用し、<package_name> をダウンロードしたパッケージ名に置き換えてインストールします:

    # Debian/Ubuntu
    dpkg -i <package_name>
       
    # RHEL/CentOS 6 and 7
    rpm -Uvh <package_name>
       
    # RHEL/CentOS 8
    dnf install <package_name>
       
    # SUSE
    zypper install <package_name>
    
note
GitLab Community Editionの場合は、gitlab-eegitlab-ceに置き換えてください。

製品ドキュメントのアップグレード

これはオプションの手順です。製品ドキュメントをインストールした場合は、新しいバージョンにアップグレードする方法を参照してください。

トラブルシューティング

GitLabインストールのステータスの取得

sudo gitlab-ctl status
sudo gitlab-rake gitlab:check SANITIZE=true

RPM「パッケージは既にインストールされています」エラー

RPM を使っていて GitLab Community Edition から GitLab Enterprise Edition にアップグレードする場合、このようなエラーが出ることがあります:

package gitlab-7.5.2_omnibus.5.2.1.ci-1.el7.x86_64 (which is newer than gitlab-7.5.2_ee.omnibus.5.2.1.ci-1.el7.x86_64) is already installed

このバージョンチェックは--oldpackage オプションで上書きすることができます:

sudo rpm -Uvh --oldpackage gitlab-7.5.2_ee.omnibus.5.2.1.ci-1.el7.x86_64.rpm

インストールしたパッケージによって廃止されたパッケージ

CEパッケージとEEパッケージは、同時にインストールされないように、互いに置き換えられるようにマークされています。

CEからEE、またはその逆を行うために内部RPMファイルを使用する場合、パッケージのインストールにはyum ではなくrpm を使用してください。 yumを使用しようとすると、次のようなエラーが発生する可能性があります:

Cannot install package gitlab-ee-11.8.3-ee.0.el6.x86_64. It is obsoleted by installed package gitlab-ce-11.8.3-ce.0.el6.x86_64

このイシューを回避するには、次のいずれかを実行します:

プロジェクト > 設定 > リポジトリにアクセスすると 500 エラーが発生します。

このエラーは、GitLab を CE > EE > CE に変換し、EE に戻したときに発生します。プロジェクトのリポジトリ設定を表示すると、ログでこのエラーを見ることができます:

Processing by Projects::Settings::RepositoryController#show as HTML
  Parameters: {"namespace_id"=>"<namespace_id>", "project_id"=>"<project_id>"}
Completed 500 Internal Server Error in 62ms (ActiveRecord: 4.7ms | Elasticsearch: 0.0ms | Allocations: 14583)

NoMethodError (undefined method `commit_message_negative_regex' for #<PushRule:0x00007fbddf4229b8>
Did you mean?  commit_message_regex_change):

このエラーは、EEへの最初の移行時に、EEの機能がCEインスタンスに追加されたために発生します。インスタンスが CE に戻され、再び EE にアップグレードされると、push_rules テーブルがすでにデータベースに存在します。そのため、マイグレーションでcommit_message_regex_change 列を追加できません。

この結果、EE テーブルのバックポート マイグレーションが正しく機能しなくなります。バックポート マイグレーションでは、CE の実行時にデータベース内の特定のテーブルが存在しないことを前提としています。

このイシューを修正するには

  1. データベース・コンソールを起動します:

    GitLab 14.2以降の場合:

    sudo gitlab-rails dbconsole --database main
    

    GitLab 14.1以前の場合:

    sudo gitlab-rails dbconsole
    
  2. 手動でcommit_message_negative_regex カラムを追加してください:

    ALTER TABLE push_rules ADD COLUMN commit_message_negative_regex VARCHAR;
       
    # Exit psql
    \q
    
  3. GitLabを再起動します:

    sudo gitlab-ctl restart
    

別のGitLab PagesサーバーでのエラーFailed to connect to the internal GitLab API

GitLab Pages 管理のトラブルシューティングをご覧ください。

An error occurred during the signature verification 実行時のエラーapt-get update

GitLabパッケージサーバーのGPGキーを更新するには、以下を実行してください:

curl --silent "https://packages.gitlab.com/gpg.key" | apt-key add -
apt-get update

Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails] [..] Command timed out after 3600s

データベーススキーマとデータの変更(データベースのマイグレーション)の実行に1時間以上かかる場合、アップグレードはtimed out エラーで失敗します:

FATAL: Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails] (gitlab::database_migrations line 51)
had an error: Mixlib::ShellOut::CommandTimeout: bash[migrate gitlab-rails database]
(/opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/resources/rails_migration.rb line 16)
had an error: Mixlib::ShellOut::CommandTimeout: Command timed out after 3600s:

このエラーを修正するには、以下の手順に従います:

  1. 残りのデータベースマイグレーションを実行してください:

    sudo gitlab-rake db:migrate
    

    このコマンドの完了には非常に長い時間がかかることがあります。SSH セッションが落ちてもプログラムが中断されないように、screen またはその他のメカニズムを使用してください。

  2. アップグレードを完了します:

    sudo gitlab-ctl reconfigure
    
  3. ホットリロードpuma およびsidekiq サービス:

    sudo gitlab-ctl hup puma
    sudo gitlab-ctl restart sidekiq
    

アセットファイルがありません

アップグレード後、GitLabが画像やJavaScript、スタイルシートなどのアセットを正しく提供していない可能性があります。500エラーが発生したり、ウェブUIが正しくレンダリングされないかもしれません。

スケールアウトされたGitLab環境では、ロードバランサーの背後にある1つのウェブサーバーがこのイシューを示している場合、問題は断続的に発生します。

アセットを再コンパイルする Rake タスクは/opt/gitlab/embedded/service/gitlab-rails/public/assetsからコンパイル済みのアセットを提供する Omnibus インストールには適用されません。

考えられる原因と修正

古いプロセス

最も可能性の高い原因は、古いPumaプロセスが実行されていて、GitLabの以前のリリースからアセットファイルをリクエストするようクライアントに指示していることです。ファイルはもう存在しないので、HTTP 404エラーが返されます。

古いPumaプロセスが実行されていないことを確認するには、再起動するのが一番です。

または

  1. ストップ・プーマ:

    gitlab-ctl stop puma
    
  2. Puma プロセスが残っていないか確認し、終了させます:

    ps -ef | egrep 'puma[: ]'
    kill <processid>
    
  3. Puma プロセスの実行が停止していることをps で確認します。

  4. Pumaの起動

    gitlab-ctl start puma
    

スプロケットファイルの重複

コンパイルされたアセットファイルはリリースごとに一意のファイル名を持っています。sprockets ファイルは、アプリケーションコードのファイル名と一意のファイル名とのマッピングを提供します。

/opt/gitlab/embedded/service/gitlab-rails/public/assets/.sprockets-manifest*.json

sprocketsファイルは1つだけにしてください。Railsは最初のものを使用します。

Omnibus GitLabのアップグレード時に、sprocketsファイルの重複チェックが実行されます:

GitLab discovered stale file(s) from the previous install that need to be cleaned up.
The following files need to be removed:

/opt/gitlab/embedded/service/gitlab-rails/public/assets/.sprockets-manifest-e16fdb7dd73cfdd64ed9c2cc0e35718a.json

これを解決するためのオプションは以下の通りです:

  • パッケージのアップグレードの出力がある場合は、指定されたファイルを削除してください。その後、Pumaを再起動してください:

     gitlab-ctl restart puma
    
  • メッセージが表示されない場合は、再インストール (詳細は以下の不完全インストールを参照してください) を実行して、再度メッセージを生成してください。

  • すべてのsprocketsファイルを削除してから、不完全インストールの指示に従ってください。

不完全インストール

不完全なインストールがこのイシューの原因である可能性があります。

これが問題かどうかを判断するために、パッケージを確認してください:

  • Debianディストリビューションの場合:

     apt-get install debsums
     debsums -c gitlab-ee
    
  • Red Hat/SUSE(RPM) ディストリビューションの場合:

     rpm -V gitlab-ee
    

不完全なインストールを修正するためにパッケージを再インストールするには:

  1. インストールされているバージョンの確認

    • Debianディストリビューションの場合:

       apt --installed list gitlab-ee
      
    • Red Hat/SUSE(RPM) ディストリビューションの場合:

       rpm -qa gitlab-ee
      
  2. インストールされているバージョンを指定してパッケージを再インストールします。例:14.4.0 Enterprise Edition:

    • Debianディストリビューションの場合:

       apt-get install --reinstall gitlab-ee=14.4.0-ee.0
      
    • Red Hat/SUSE(RPM) ディストリビューションの場合:

       yum reinstall gitlab-ee-14.4.0
      

NGINX Gzip サポート

nginx['gzip_enabled'] が無効になっていないか確認してください:

grep gzip /etc/gitlab/gitlab.rb

一部のアセットが配信されない可能性があります。詳しくは関連イシューをご覧ください。