GitLab のアップグレード

GitLabのアップグレードは比較的簡単な作業ですが、インストール方法やGitLabのバージョンの古さ、メジャーバージョンへのアップグレードかどうかなどによって複雑さが変わってきます。

すべてのアップグレード方法に関連する情報が含まれているので、必ずページ全体を読んでください。

メンテナンスポリシーの文書には、アップグレードに関する追加情報があります:

  • GitLab 製品のバージョン管理の解釈方法。
  • どのリリースを実行すべきかについての推奨事項。
  • パッチとセキュリティパッチリリースの使用方法。
  • コードの変更をバックポートするとき。

インストール方法によるアップグレード

インストール方法とGitLabのバージョンによって、GitLabをアップグレードする公式な方法は複数あります:

Linuxパッケージ (Omnibus)

パッケージアップグレードガイドには、GitLab公式リポジトリでインストールされたパッケージをアップグレードするために必要な手順がコンテナされています。

特定のバージョンにアップグレードしたい場合の手順もあります。

セルフコンパイルによるインストール

以前はアップグレードの手順を別々の文書で説明していましたが、現在は1つの文書にまとめました。以前のアップグレードガイドラインは Git リポジトリにあります:

Dockerを使ったインストール

GitLabは公式のDockerイメージをCommunity版とEnterprise版の両方に提供しており、それらはOmnibusパッケージをベースにしています。Dockerを使ったGitLabのインストール方法をご覧ください。

Helmを使ったインストール

GitLabはHelmを使ってKubernetesクラスターにデプロイすることができます。クラウドネイティブなデプロイをアップグレードする方法については、別のドキュメントで説明します。

ChartバージョンからGitLabバージョンへのバージョンマッピングを使用して、アップグレードパスを決定します。

アップグレードの計画

GitLabのアップグレードを計画するためのガイドをご覧ください。

アップグレード前にバックグラウンドマイグレーションをチェック

リリースによっては、新しいバージョンにアップグレードする前に、異なるマイグレーションを完了する必要がある場合があります。

詳細については、バックグラウンドマイグレーションを参照してください。

CI/CD パイプラインとジョブの実行への対応

GitLab Runnerがジョブを処理している間にGitLabインスタンスをアップグレードすると、トレースアップデートが失敗します。GitLab がオンラインに戻ると、トレースアップデートは自己回復するはずです。しかし、エラーによっては、GitLab Runnerはジョブの処理を再試行するか、最終的に終了します。

アーティファクトに関しては、GitLab Runnerは3回アップロードを試みます。

上記の2つのシナリオにアドレスするには、アップグレードの前に以下のことを行うことをお勧めします:

  1. メンテナンスの計画を立てましょう。
  2. /etc/gitlab/gitlab.rbに以下を追加することで、ランナーを一時停止したり、新しいジョブの開始をブロックすることができます:

    nginx['custom_gitlab_server_config'] = "location /api/v4/jobs/request {\n deny all;\n return 503;\n}\n"
    

    でGitLabを再設定します:

    sudo gitlab-ctl reconfigure
    
  3. すべてのジョブが終了するまで待ちます。
  4. GitLabをアップグレードします。
  5. GitLab RunnerをGitLabバージョンと同じバージョンにアップグレードしてください。両方のバージョンが同じである必要があります。
  6. Runner の一時停止を解除し、以前の/etc/gitlab/gitlab.rb の変更を戻して新しいジョブの開始をブロックしないようにします。

保留中の高度な検索マイグレーションのチェック

このセクションはElasticsearch インテグレーションを有効にしている場合にのみ適用されます。 .

メジャーリリースでは、メジャーバージョンアップグレードの前に、現在のバージョンで最新のマイナーリリースからすべての高度な検索のマイグレーションが完了している必要があります。以下のコマンドを実行することで、保留中のマイグレーションを見つけることができます。

Linux package (Omnibus)
sudo gitlab-rake gitlab:elastic:list_pending_migrations
Self-compiled (source)
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations

高度な検索マイグレーションが行き詰まったらどうしますか?

GitLab 15.0では、DeleteOrphanedCommit という名前の高度な検索マイグレーションが、アップグレードの間、保留状態で永久に立ち往生することがあります。このイシューはGitLab 15.1で修正されました。

GitLab 15.0を高度な検索で使用しているセルフマネージドカスタマーの場合、パフォーマンスの低下が発生します。マイグレーションをクリーンアップするには、15.1以降にアップグレードしてください。

保留中の他の高度な検索マイグレーションについては、停止したマイグレーションを再試行する方法をご覧ください。

保留中の高度な検索マイグレーションがすべて完了する前に GitLab をアップグレードした場合、新しいバージョンで削除された保留中のマイグレーションは実行も再試行もできません。この場合、インデックスを一から作成し直す必要があります。

エラーの対処法Elasticsearch version not compatible

ElasticsearchまたはOpenSearchのバージョンがGitLabのバージョンと互換性があることを確認してください。

ダウンタイムなしのアップグレード

ダウンタイムなしでアップグレードする方法をお読みください。

新しいメジャーバージョンへのアップグレード

メジャーバージョンのアップグレードには、より注意が必要です。後方互換性のない変更はメジャーバージョンに予約されています。メジャーバージョン間のアップグレードがシームレスであることは保証できませんので、注意深く指示に従ってください。

メジャーバージョンアップには以下の手順が必要です:

  1. サポートされているアップグレードパスを確認します。
  2. 新しいメジャーバージョンにアップグレードする前に、バックグラウンドマイグレーションが完全に完了していることを確認します。
  3. Elasticsearch インテグレーションを有効にしている場合は、メジャーバージョンのアップグレードを行う前に、すべての高度な検索のマイグレーションが完了していることを確認してください。
  4. GitLabインスタンスに関連するRunnerがある場合、それらを現在のGitLabバージョンに合わせてアップグレードすることが非常に重要です。これはGitLabバージョンとの互換性を保証します。

アップグレードパス

複数のGitLabバージョンを一度にアップグレードすることは、ダウンタイムを受け入れることによってのみ可能です。ダウンタイムを受け入れたくない場合は、ダウンタイムゼロでアップグレードする方法をお読みください。

サポートされているアップグレードパスの例をダイナミックに表示するには、GitLabサポートチームがメンテナンスしているアップグレードパスツールをお試しください。フィードバックを共有し、ツールの改善に役立てるには、アップグレードパスプロジェクトでイシューを作成するか、MRを作成してください。

アップグレードするとき

  1. お使いのバージョンがアップグレードパスのどの位置にあるかを確認してください:

  2. 必要なアップグレードストップを確認してください。
  3. バージョンごとのアップグレード手順を参照してください。
  4. それに従って GitLab をアップグレードしてください。
note
明示的に指定されていない場合、GitLab をアップグレードするときは、最初のパッチリリースではなく、major.minor リリースで利用可能な最新のパッチリリースにアップグレードしてください。たとえば、13.8.0ではなく13.8.8 のように。これには、major.minor バージョンも含まれます。アップグレードプロセスに関連するイシューが修正されている可能性があるため、アップグレードパスの途中で停止する必要があります。特にメジャーバージョン周辺では、重要なデータベーススキーマやマイグレーションのパッチが最新のパッチリリースに含まれている可能性があります。

必要なアップグレード停止位置

必須アップグレードストップは、それ以降のバージョンにアップグレードする前にアップグレードしなければならないGitLabのバージョンです。必須アップグレードストップは、必要なバックグラウンドマイグレーションを終了させます。

GitLab 16.xでは、ユーザーが適切なアップグレードストップと必要な場合のダウンタイムを計画しやすいように、必須アップグレードストップのスケジュールを事前に設定しています。

予定されている最初の必須アップグレード停止は16.3で発表されました。アップグレードを計画する際には、これを考慮してください。

以前のGitLabバージョン

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

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

エディション間のアップグレード

GitLabには2つの種類があります:MITライセンスのCommunity Editionと、Community Editionの上に構築され、主に100人以上のユーザーを対象とした追加機能を含むEnterprise Editionです。

以下に、GitLabのエディションを変更する際に役立つガイドをいくつか紹介します。

コミュニティ版からエンタープライズ版へ

note
以下のガイドは、Enterprise Editionをご契約の方のみを対象としています。

GitLabのインストールをCommunity EditionからEnterprise Editionにアップグレードする場合は、インストール方法に応じて以下のガイドに従ってください:

  • ソースCEからEEへのアップグレードガイド- 手順はバージョンアップと非常に似ています:サーバーを停止し、コードを取得し、新しい機能のために設定ファイルを更新し、ライブラリをインストールしてマイグレーションを行い、initスクリプトを更新し、アプリケーションを起動してステータスを確認します。
  • Omnibus CE to EE- このガイドに従って、Omnibus GitLab Community EditionをEnterprise Editionにアップグレードしてください。
  • Docker CE to EE- このガイドに従って、GitLab Community EditionのコンテナをEnterprise Editionのコンテナにアップグレードしてください。
  • Helm chart (Kubernetes) CE to EE- GitLab Community EditionのHelmデプロイをEnterprise Editionにアップグレードするには、このガイドに従ってください。

エンタープライズ版からコミュニティ版へ

Enterprise EditionのインストールをCommunity Editionにダウングレードするには、このガイドに従ってください。

バージョン別アップグレード手順

毎月、GitLabのメジャーリリースやマイナーリリース、場合によってはパッチリリースがリリースポストとともに公開されます。あなたが引き継ぐすべてのバージョンのリリース投稿を読むべきです。メジャーリリースとマイナーリリースの投稿の最後には、特に探すべき3つのセクションがあります:

  • 非推奨事項
  • 削除
  • アップグレードに関する重要な注意事項

以下が含まれます:

  • アップグレードの一環として実行しなければならないステップ。例えば、8.12ではElasticsearchインデックスを再作成する必要がありました。古いバージョンのGitLabを8.12以降にアップグレードする場合は、この作業が必要になります。
  • サポートしているソフトウェアのバージョンの変更(GitLab 13でIE11のサポートを終了するなど)。

このセクションの説明とは別に、GitLabをどのようにインストールしたかに応じて、インストール固有のアップグレード手順も確認してください:

note
RubyとGitのバージョンに関連する以下の特定の情報は、Omnibusのインストールと Helm Chartのデプロイには当てはまりません。これらは適切なRubyとGitのバージョンで提供されており、RubyとGitのシステムバイナリは使用していません。この2つのアプローチを利用する場合、RubyやGitをインストールする必要はありません。

GitLab 16

GitLab 16にアップグレードする前に、GitLab 16の変更点をご覧ください。

GitLab 15

GitLab 15にアップグレードする前に、GitLab 15の変更点をご覧ください。

GitLab 14

GitLab 14にアップグレードする前に、GitLab 14の変更点をご覧ください。

15.9.xでのユーザープロファイルのデータ消失バグ

15.9.0、15.9.1、15.9.2 のデータベースマイグレーションで、ユーザープロファイルのフィールドlinkedintwitterskypewebsite_urllocationorganizationからデータが失われるバグがあります。

このバグはパッチリリース15.9.3以降で修正されています。

以下のアップグレードパスでもこのバグを回避できます:

  1. GitLab 15.6.x、15.7.x、または15.8.xにアップグレードしてください。
  2. バッチバックグランドマイグレーションが完了していることを確認します。
  3. バグ修正のない以前のGitLab 15.9パッチリリースにアップグレードしてください。

このイシューのために15.9.3以降にアップグレードする必要はありません。

詳しくはイシューをお読みください。

Gitaly:Omnibus GitLabの設定変更

Omnibus GitLabのGitaly設定構造がGitLab 16.0で変更され、セルフコンパイルインストールで使用されるGitaly設定構造と一致するようになりました。

この変更の結果、gitaly['configuration'] の下の単一のハッシュがほとんどのGitaly設定を保持します。いくつかのgitaly['..'] 設定オプションは、Omnibus GitLab 16.0以降でも引き続き使用されます:

  • enable
  • dir
  • bin_path
  • env_directory
  • env
  • open_files_ulimit
  • consul_service_name
  • consul_service_meta

既存の設定を新構造の下にマイグレーションしてください。新しい構造はOmnibus GitLab 15.10からサポートされています。

新構造は以下の通りです。旧キーは新キーの上にコメントとして記述されています。新構造を設定に適用する場合:

  1. ... を古いキーの値に置き換えてください。
  2. 以前に値を設定していないキーはスキップしてください。
  3. マイグレーションが完了したら、古いキーを設定から削除します。
  4. オプションですが、推奨します。すべてのハッシュキーの末尾にカンマを含めることで、キーの並び替えやキーの追加を行ってもハッシュを有効に保つことができます。
  5. git_data_dirs を置き換えるためにstorage を設定する場合、以下に説明するようにrepositories をパスに追加する必要があります。このステップを省略すると、設定が修正されるまで Git リポジトリにアクセスできなくなります。
gitaly['configuration'] = {
# gitaly['socket_path']
socket_path: ...,
# gitaly['runtime_dir']
runtime_dir: ...,
# gitaly['listen_addr']
listen_addr: ...,
# gitaly['prometheus_listen_addr']
prometheus_listen_addr: ...,
# gitaly['tls_listen_addr']
tls_listen_addr: ...,
tls: {
  # gitaly['certificate_path']
  certificate_path: ...,
  # gitaly['key_path']
  key_path: ...,
},
# gitaly['graceful_restart_timeout']
graceful_restart_timeout: ...,
logging: {
  # gitaly['logging_level']
  level: ...,
  # gitaly['logging_format']
  format: ...,
  # gitaly['logging_sentry_dsn']
  sentry_dsn: ...,
  # gitaly['logging_ruby_sentry_dsn']
  ruby_sentry_dsn: ...,
  # gitaly['logging_sentry_environment']
  sentry_environment: ...,
  # gitaly['log_directory']
  dir: ...,
},
prometheus: {
  # gitaly['prometheus_grpc_latency_buckets']. The old value was configured as a string
  # such as '[0, 1, 2]'. The new value must be an array like [0, 1, 2].
  grpc_latency_buckets: ...,
},
auth: {
  # gitaly['auth_token']
  token: ...,
  # gitaly['auth_transitioning']
  transitioning: ...,
},
git: {
  # gitaly['git_catfile_cache_size']
  catfile_cache_size: ...,
  # gitaly['git_bin_path']
  bin_path: ...,
  # gitaly['use_bundled_git']
  use_bundled_binaries: ...,
  # gitaly['gpg_signing_key_path']
  signing_key: ...,
  # gitaly['gitconfig']. This is still an array but the type of the elements have changed.
  config: [
    {
      # Previously the elements contained 'section', and 'subsection' in addition to 'key'. Now
      # these all should be concatenated into just 'key', separated by dots. For example,
      # {section: 'first', subsection: 'middle', key: 'last', value: 'value'}, should become
      # {key: 'first.middle.last', value: 'value'}.
      key: ...,
      value: ...,
    },
  ],
},
# Storage could previously be configured through either gitaly['storage'] or 'git_data_dirs'. Migrate
# the relevant configuration according to the instructions below.
# For 'git_data_dirs', migrate only the 'path' to the gitaly['configuration'] and leave the rest of it untouched.
storage: [
  {
    # gitaly['storage'][<index>]['name']
    #
    # git_data_dirs[<name>]. The storage name was configured as a key in the map.
    name: ...,
    # gitaly['storage'][<index>]['path']
    #
    # git_data_dirs[<name>]['path']. Use the value from git_data_dirs[<name>]['path'] and append '/repositories' to it.
    #
    # For example, if the path in 'git_data_dirs' was '/var/opt/gitlab/git-data', use
    # '/var/opt/gitlab/git-data/repositories'. The '/repositories' extension was automatically
    # appended to the path configured in `git_data_dirs`.
    path: ...,
  },
],
hooks: {
  # gitaly['custom_hooks_dir']
  custom_hooks_dir: ...,
},
daily_maintenance: {
  # gitaly['daily_maintenance_disabled']
  disabled: ...,
  # gitaly['daily_maintenance_start_hour']
  start_hour: ...,
  # gitaly['daily_maintenance_start_minute']
  start_minute: ...,
  # gitaly['daily_maintenance_duration']
  duration: ...,
  # gitaly['daily_maintenance_storages']
  storages: ...,
},
cgroups: {
  # gitaly['cgroups_mountpoint']
  mountpoint: ...,
  # gitaly['cgroups_hierarchy_root']
  hierarchy_root: ...,
  # gitaly['cgroups_memory_bytes']
  memory_bytes: ...,
  # gitaly['cgroups_cpu_shares']
  cpu_shares: ...,
  repositories: {
    # gitaly['cgroups_repositories_count']
    count: ...,
    # gitaly['cgroups_repositories_memory_bytes']
    memory_bytes: ...,
    # gitaly['cgroups_repositories_cpu_shares']
    cpu_shares: ...,
  }
},
# gitaly['concurrency']. While the structure is the same, the string keys in the array elements
# should be replaced by symbols as elsewhere. {'key' => 'value'}, should become {key: 'value'}.
concurrency: ...,
# gitaly['rate_limiting']. While the structure is the same, the string keys in the array elements
# should be replaced by symbols as elsewhere. {'key' => 'value'}, should become {key: 'value'}.
rate_limiting: ...,
pack_objects_cache: {
  # gitaly['pack_objects_cache_enabled']
  enabled: ...,
  # gitaly['pack_objects_cache_dir']
  dir: ...,
  # gitaly['pack_objects_cache_max_age']
  max_age: ...,
}
}

Praefect:Omnibus GitLab設定の変更

Omnibus GitLabのPraefect設定構造がGitLab 16.0で変更され、セルフコンパイルインストールで使用されるPraefect設定構造と一致するようになりました。

この変更により、praefect['configuration'] の下にある単一のハッシュがほとんどの Praefect 設定を保持します。一部のpraefect['..'] 設定オプションは、Omnibus GitLab 16.0 以降でも引き続き使用されます:

  • enable
  • dir
  • log_directory
  • env_directory
  • env
  • wrapper_path
  • auto_migrate
  • consul_service_name

既存の設定を新しい構造下に移動してマイグレーションしてください。新しい構造は、Omnibus GitLab 15.9からサポートされています。

新構造は以下の通りです。旧キーは新キーの上にコメントとして記述されています。新構造を設定に適用する場合:

  1. ... を古いキーの値に置き換えてください。
  2. 以前に値を設定していないキーはスキップしてください。
  3. マイグレーションが完了したら、古いキーを設定から削除します。
  4. オプションですが、推奨します。すべてのハッシュキーの末尾にカンマを含めることで、キーの並び替えやキーの追加を行ってもハッシュを有効に保つことができます。
praefect['configuration'] = {
  # praefect['listen_addr']
  listen_addr: ...,
  # praefect['socket_path']
  socket_path: ...,
  # praefect['prometheus_listen_addr']
  prometheus_listen_addr: ...,
  # praefect['tls_listen_addr']
  tls_listen_addr: ...,
  # praefect['separate_database_metrics']
  prometheus_exclude_database_from_default_metrics: ...,
  auth: {
    # praefect['auth_token']
    token: ...,
    # praefect['auth_transitioning']
    transitioning: ...,
  },
  logging: {
    # praefect['logging_format']
    format: ...,
    # praefect['logging_level']
    level: ...,
  },
  failover: {
    # praefect['failover_enabled']
    enabled: ...,
  },
  background_verification: {
    # praefect['background_verification_delete_invalid_records']
    delete_invalid_records: ...,
    # praefect['background_verification_verification_interval']
    verification_interval: ...,
  },
  reconciliation: {
    # praefect['reconciliation_scheduling_interval']
    scheduling_interval: ...,
    # praefect['reconciliation_histogram_buckets']. The old value was configured as a string
    # such as '[0, 1, 2]'. The new value must be an array like [0, 1, 2].
    histogram_buckets: ...,
  },
  tls: {
    # praefect['certificate_path']
    certificate_path: ...,
    # praefect['key_path']
    key_path: ...,
  },
  database: {
    # praefect['database_host']
    host: ...,
    # praefect['database_port']
    port: ...,
    # praefect['database_user']
    user: ...,
    # praefect['database_password']
    password: ...,
    # praefect['database_dbname']
    dbname: ...,
    # praefect['database_sslmode']
    sslmode: ...,
    # praefect['database_sslcert']
    sslcert: ...,
    # praefect['database_sslkey']
    sslkey: ...,
    # praefect['database_sslrootcert']
    sslrootcert: ...,
    session_pooled: {
      # praefect['database_direct_host']
      host: ...,
      # praefect['database_direct_port']
      port: ...,
      # praefect['database_direct_user']
      user: ...,
      # praefect['database_direct_password']
      password: ...,
      # praefect['database_direct_dbname']
      dbname: ...,
      # praefect['database_direct_sslmode']
      sslmode: ...,
      # praefect['database_direct_sslcert']
      sslcert: ...,
      # praefect['database_direct_sslkey']
      sslkey: ...,
      # praefect['database_direct_sslrootcert']
      sslrootcert: ...,
    }
  },
  sentry: {
    # praefect['sentry_dsn']
    sentry_dsn: ...,
    # praefect['sentry_environment']
    sentry_environment: ...,
  },
  prometheus: {
    # praefect['prometheus_grpc_latency_buckets']. The old value was configured as a string
    # such as '[0, 1, 2]'. The new value must be an array like [0, 1, 2].
    grpc_latency_buckets: ...,
  },
  # praefect['graceful_stop_timeout']
  graceful_stop_timeout: ...,

  # praefect['virtual_storages']. The old value was a hash map but the new value is an array.
  virtual_storage: [
    {
      # praefect['virtual_storages'][VIRTUAL_STORAGE_NAME]. The name was previously the key in
      # the 'virtual_storages' hash.
      name: ...,
      # praefect['virtual_storages'][VIRTUAL_STORAGE_NAME]['nodes'][NODE_NAME]. The old value was a hash map
      # but the new value is an array.
      node: [
        {
          # praefect['virtual_storages'][VIRTUAL_STORAGE_NAME]['nodes'][NODE_NAME]. Use NODE_NAME key as the
          # storage.
          storage: ...,
          # praefect['virtual_storages'][VIRTUAL_STORAGE_NAME]['nodes'][NODE_NAME]['address'].
          address: ...,
          # praefect['virtual_storages'][VIRTUAL_STORAGE_NAME]['nodes'][NODE_NAME]['token'].
          token: ...,
        },
      ],
    }
  ]
}

GitLab 15.3でPraefectが生成するレプリカパスに変更。

Gitalyクラスターで作成された新しいGitリポジトリは、@hashed のストレージパスを使用しなくなりました。

PraefectはGitalyクラスターで使用するレプリカパスを生成するようになりました。この変更は、GitalyクラスターがGitリポジトリをアトミックに作成、削除、リネームするための前提条件です。

レプリカパスを特定するには、Praefect リポジトリのメタデータをクエリし、@hashed ストレージパスを-relative-path に渡します。

この情報があれば、サーバーフックを正しくインストールできます。

PostgreSQLのセグメンテーション障害のイシュー

外部のPostgreSQL、特にAWS RDSでGitLabを実行する場合は、GitLab 14.8以降にアップグレードする前に、PostgreSQLのパッチレベルを最低でも12.7または13.3にアップグレードしてください。

GitLab Enterprise Editionの14.8とGitLab Community Editionの15.1では、Loose Foreign KeysというGitLabの機能が有効になりました。

この機能が有効になった後、セグメンテーションフォールトを引き起こすデータベースエンジンのバグが原因でPostgreSQLが計画外に再起動するというレポーターが報告されています。

詳細はイシューを参照してください。

GitLab 14.6.0 から 14.7.2 における LFS オブジェクトのインポートとミラーのイシュー

Geo が有効な場合、インポートまたはミラーリングされたプロジェクトで LFS オブジェクトの保存に失敗します。

このバグはGitLab 14.8.0 で修正され、14.7.3 にバックポートされました。

GitLab 13.9から14.4のメンテナンスモードのイシュー

メンテナンスモードが有効な場合、ユーザーはSSO、SAML、LDAPでサインインできません。

メンテナンスモードを有効にする前にサインインしていたユーザーは、引き続きサインインできます。メンテナンスモードを有効にした管理者のセッションが失われた場合、UI からメンテナンスモードを無効にすることはできません。その場合は、APIまたはRailsコンソールからMaintenanceモードを無効にできます。

このバグはGitLab 14.5.0で修正され、14.4.3と14.3.5にバックポートされました。

その他