GitHub Enterprise Server をアップグレードする

アップグレードの準備

1. アップグレードの戦略を決定し、アップグレード先のバージョンを選択してください。 詳細については、「アップグレード要件」を参照してください。また、「Upgrade assistant」を参照し、現在のリリース バージョンからのアップグレード パスを確認してください。

2. GitHub Enterprise Server Backup Utilitiesで、プライマリインスタンスの新しいバックアップを作成してください。 詳しくは、GitHub Enterprise Server Backup Utilities プロジェクト ドキュメントの README.md ファイルを参照してください。

   注: GitHub Enterprise Server Backup Utilities バージョンは、your GitHub Enterprise Server instanceと同じバージョンであるか、最大で 2 つ前のバージョンである必要があります。 詳しくは、「GitHub Enterprise Server Backup Utilities のアップグレード」を参照してください。

3. your GitHub Enterprise Server instanceが GitHub Actions にエフェメラル セルフホステッド ランナーを使っていて、自動更新を無効にしている場合、アップグレードされたインスタンスが実行するランナー アプリケーションのバージョンにランナーをアップグレードしてください。

4. アップグレードパッケージを使ってアップグレードをする場合は、GitHub Enterprise Server のエンドユーザのためにメンテナンス時間枠をスケジューリングしてください。 ホットパッチを利用している場合、メンテナンスモードは必要ありません。

   注: メンテナンス期間は、実行するアップグレードの種類によって変わります。 ホットパッチを利用するアップグレードは、通常メンテナンスウィンドウを必要としません。 リブートが必要になることもあります。そのリブートは後で行うことができます。 MAJOR.FEATURE.PATCH というバージョン付けのスキームに従い、アップグレードパッケージを使ったパッチのリリースで生じるダウンタイムは、通常 5 分未満です。 データの移行を含むフィーチャリリースは、ストレージの性能および移行するデータの量に応じた時間がかかります。 詳細については、「メンテナンスモードの有効化とスケジューリング」を参照してください。

スナップショットの取得

スナップショットは、ある時点での仮想マシン（VM）のチェックポイントです。 アップグレードに失敗した場合にスナップショットからVMを回復できるよう、仮想マシンをアップグレードする前にスナップショットを取っておくことを強くおすすめします。 アプライアンスの電源が切れているか、メンテナンス モードであり、すべてのバックグラウンド ジョブが完了している場合にのみ、VM スナップショットを作成することをお勧めします。

新しいフィーチャリリースにアップグレードするなら、VM のスナップショットを取らなければなりません。 パッチリリースへのアップグレードをするなら、既存のデータディスクをアタッチできます。

スナップショットには2種類あります。

• VM スナップショットは、ユーザー データと構成データを含む VM の状態全体を保存します。 このスナップショットの手法には大量のディスク領域が必要になり、時間がかかります。

• データ ディスク スナップショットは、ユーザー データのみを保存します。

  注:

  • プラットフォームによっては、ユーザのデータディスクだけのスナップショットを取ることができません。 それらのプラットフォームでは、VM 全体のスナップショットを取る必要があります。
  • ハイパーバイザーが完全なVMスナップショットをサポートしていないなら、ルートディスクとデータディスクのスナップショットを時間をおかずに取らなければなりません。

プラットフォーム	Snapshot メソッド	スナップショットドキュメンテーションのURL
Amazon AWS	ディスク	https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-creating-snapshot.html
Azure	VM	https://docs.microsoft.com/azure/backup/backup-azure-vms-first-look-arm
Hyper-V	VM	https://docs.microsoft.com/windows-server/virtualization/hyper-v/manage/enable-or-disable-checkpoints-in-hyper-v
Google Compute Engine	ディスク	https://cloud.google.com/compute/docs/disks/create-snapshots
VMware	VM	https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.hostclient.doc/GUID-64B866EF-7636-401C-A8FF-2B4584D9CA72.html

ホットパッチでのアップグレード

ホットパッチを使って GitHub Enterprise Server を最新のパッチ リリースにアップグレードできます。

ホットパッチは新しいパッチリリースへのアップグレードに利用できますが、新しいフィーチャリリースへのアップグレードには利用できません。 たとえば、2.10.1 から 2.10.5 は同じ機能シリーズに含まれているためアップグレードできますが、2.10.9 から 2.11.0 は異なる機能シリーズに含まれているためアップグレードできません。

ホットパッチでは通常、再起動は必要ありません。 ホットパッチで再起動が必要になる場合、GitHub Enterprise Server リリース ノートに要件が示されます。

ホットパッチには構成実行が必要です。構成実行すると、your GitHub Enterprise Server instance の一部または全部のサービスで短い時間、エラーが発生したり、応答しなかったりすることがあります。 ホットパッチのインストール中はメンテナンス モードを有効にする必要はありませんが、有効にすると、エラーまたはタイムアウトではなくメンテナンス ページがユーザーに表示されます。 詳細については、「メンテナンスモードの有効化とスケジューリング」を参照してください。

Management Console を使うと、ホットパッチをすぐにインストールすることや、後でインストールするようにスケジュールすることができます。 管理シェルで、ghe-upgrade ユーティリティを使ってホットパッチをインストールすることもできます。 詳細については、「アップグレード要件」を参照してください。

ホットパッチでの単一のアプライアンスのアップグレード

Management Console を使ってホットパッチをインストールする

Management Console を使って自動更新を有効にすることで、ホットパッチを使ってアップグレードできます。 そうすると、アップグレード可能な GitHub Enterprise Server の最新バージョンが表示されます。

表示されたアップグレード ターゲットがパッチ リリースではなく、機能リリースであった場合は、Management Console を使ってホットパッチをインストールすることはできません。 代わりに管理シェルを使ってホットパッチをインストールする必要があります。 詳細については、「管理シェルを使ったホットパッチのインストール」を参照してください。

1. 自動更新を有効にする。 詳細については、自動更新の有効化に関するページを参照してください。

2. GitHub Enterprise Server の管理アカウントから、任意のページの右上隅の をクリックします。

   

3. [サイト管理者] ページにまだ表示されていない場合は、左上隅の [サイト管理者] をクリックします。

   1. 左側のサイドバーで、 Management Console をクリックします。 1. Management Console の上部にある [更新] をクリックします。

4. 新しいホットパッチがダウンロードされたなら、Install package（パッケージのインストール）ドロップダウンメニューを使ってください。

   • すぐにインストールするには、 Now を選びます。
   • 後でインストールするなら、後の日付を選択してください。

5. [インストール] をクリックします。

管理シェルを使ったホットパッチのインストール

1. your GitHub Enterprise Server instance に SSH で接続します。 インスタンスが複数のノードで構成されている場合は (高可用性や geo レプリケーションが構成されている場合など)、プライマリ ノードに SSH 接続します。 クラスターを使用する場合は、任意のノードに SSH 接続できます。 SSH 接続について詳しくは、「管理シェル (SSH) にアクセスする」をご覧ください。

   $ ssh -p 122 admin@HOSTNAME

2. GitHub Enterprise Server リリース ページを参照します。 アップグレード先対象リリースの横にある [ダウンロード] をクリックし、 [アップグレード] タブをクリックします。アップグレードのホットパッケージ ( .hpkg ファイル) の URL をコピーします。

3. curl を使って、アップグレード パッケージを your GitHub Enterprise Server instance にダウンロードします。

   admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL

4. このパッケージ ファイル名を使って ghe-upgrade コマンドを実行します。

   admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.hpkg
   *** verifying upgrade package signature...

5. カーネル、MySQL、Elasticsearch やその他のプログラムのアップグレードにリブートが必要なら、ホットパッチアップグレードスクリプトが通知してくれます。

ホットパッチを使ったレプリカインスタンスを持つアプライアンスのアップグレード

High Availability と Geo-replication が設定されたアプライアンスは、プライマリインスタンスに加えてレプリカインスタンスを使います。 これらのアプライアンスをアップグレードするには、プライマリインスタンスとすべてのレプリカインスタンスの両方を、1 つずつアップグレードしなければなりません。

プライマリインスタンスのアップグレード

1. 「管理シェルを使ったホットパッチのインストール」の手順に従ってプライマリ インスタンスをアップグレードします。

レプリカインスタンスのアップグレード

1. 「管理シェルを使ったホットパッチのインストール」の手順に従ってレプリカ インスタンスをアップグレードします。 Geo-replication に複数のレプリカを使用している場合は、この手順を繰り返して、各レプリカを一度に 1 つずつアップグレードする必要があります。

2. ポート122のSSH経由でレプリカインスタンスに"admin"ユーザとして接続してください。

   $ ssh -p 122 admin@REPLICA_HOST

   1. 以下を実行して、アップグレードを検証してください。

   $ ghe-version

アップグレードパッケージでのアップグレード

フィーチャシリーズ内の最新のパッチリリースへのアップグレードにはホットパッチが利用できますが、新しいフィーチャリリースへのアップグレードにはアップグレードパッケージを使わなければなりません。 たとえば 2.11.10 から 2.12.4 へのアップグレードの場合、これらは異なるフィーチャ シリーズなので、アップグレード パッケージを使う必要があります。 詳細については、「アップグレード要件」を参照してください。

アップグレードパッケージでの単一のアプライアンスのアップグレード

1. your GitHub Enterprise Server instance に SSH で接続します。 インスタンスが複数のノードで構成されている場合は (高可用性や geo レプリケーションが構成されている場合など)、プライマリ ノードに SSH 接続します。 クラスターを使用する場合は、任意のノードに SSH 接続できます。 SSH 接続について詳しくは、「管理シェル (SSH) にアクセスする」をご覧ください。

   $ ssh -p 122 admin@HOSTNAME

2. GitHub Enterprise Server リリース ページを参照します。 アップグレード先対象リリースの横にある [ダウンロード] をクリックし、 [アップグレード] タブをクリックします。適切なプラットフォームを選び、アップグレード パッケージ ( .pkg fファイル) の URL をコピーします。

3. curl を使って、アップグレード パッケージを your GitHub Enterprise Server instance にダウンロードします。

   admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL

4. メンテナンスモードを有効にし、GitHub Enterprise Server インスタンス上のすべてのアクティブなプロセスが完了するのを待ってください。 詳細については、「メンテナンスモードの有効化とスケジューリング」を参照してください。

   注: 「プライマリ インスタンスのアップグレード」の手順に従っている場合、高可用性構成のプライマリ アプライアンスをアップグレードするときにアプライアンスはメンテナンス モードになっているはずです。

5. このパッケージ ファイル名を使って ghe-upgrade コマンドを実行します。

   admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.pkg
   *** verifying upgrade package signature...

6. アップグレードを続けてパッケージ署名検証後に再起動することを承諾します。 新しいルートファイルシステムがセカンダリパーティションに書かれ、インスタンスは自動的にメンテナンスモードで再起動します。

   *** applying update...
   This package will upgrade your installation to version VERSION-NUMBER
   Current root partition: /dev/xvda1 [VERSION-NUMBER]
   Target root partition:  /dev/xvda2
   Proceed with installation? [y/N]

7. 必要に応じて復元を検証するには、IP アドレスの指定リストへのアクセスを許可するように IP 例外リストを構成します。 詳細については、「IP 例外リストを使い、メンテナンス モードで変更を検証する」を参照してください。

8. 単一アプライアンスのアップグレードの場合は、メンテナンス モードを無効にして、ユーザーが your GitHub Enterprise Server instanceを使用できるようにします。

   注: 高可用性構成のアプライアンスをアップグレードする場合は、すべてのレプリカをアップグレードし、レプリケーションが最新の状態になるまでは、メンテナンス モードのままにしてください。 詳細については、「レプリカ インスタンスのアップグレード」を参照してください。

アップグレードパッケージを使ったレプリカインスタンスを持つアプライアンスのアップグレード

High Availability と Geo-replication が設定されたアプライアンスは、プライマリインスタンスに加えてレプリカインスタンスを使います。 これらのアプライアンスをアップグレードするには、プライマリインスタンスとすべてのレプリカインスタンスの両方を、1 つずつアップグレードしなければなりません。

プライマリインスタンスのアップグレード

1. プライマリインスタンスでメンテナンスモードを有効化し、すべてのアクティブなプロセスが完了するのを待ちます。 詳細については、「メンテナンス モードの有効化」を参照してください。
2. ポート122のSSH経由でレプリカインスタンスに"admin"ユーザとして接続してください。

   $ ssh -p 122 admin@REPLICA_HOST

3. そのレプリカ インスタンス上、またはすべてのレプリカ インスタンス上 (geo レプリケーション の一部として複数のレプリカ インスタンスを実行している場合) で ghe-repl-stop を実行してレプリケーションを停止します。
4. 「アップグレード パッケージを使った単一アプライアンスのアップグレード」の手順に従って、プライマリ インスタンスをアップグレードします。

レプリカインスタンスのアップグレード

1. 「アップグレード パッケージを使った単一アプライアンスのアップグレード」の手順に従って、レプリカ インスタンスをアップグレードします。 Geo-replication に複数のレプリカを使用している場合は、この手順を繰り返して、各レプリカを一度に 1 つずつアップグレードする必要があります。

2. ポート122のSSH経由でレプリカインスタンスに"admin"ユーザとして接続してください。

   $ ssh -p 122 admin@REPLICA_HOST

   1. 以下を実行して、アップグレードを検証してください。

   $ ghe-version

3. レプリカのインスタンス上で ghe-repl-start を実行してレプリケーションを開始します。

4. レプリカ インスタンスで、レプリケーション サービスが正しく動作していることを確認するには、ghe-repl-status を実行します。 このコマンドは、レプリケーションが問題なく進行しており、レプリカがアップグレードされていれば、すべてのサービスに対して OK を返します。コマンドから Replication is not running が返される場合、レプリケーションはまだ起動中の可能性があります。 約 1 分待ってから、もう一度 ghe-repl-status を実行してください。

   注: 再同期の進行中、ghe-repl-status は、レプリケーションが遅れていることを示す可能性があります。 たとえば、次のようなメッセージが表示されることがあります。

   CRITICAL: git replication is behind the primary by more than 1007 repositories and/or gists
   

   • 各ノードを GitHub Enterprise Server 3.6.0 以降にアップグレードし、レプリケーションを開始したが、git replication is behind the primary が 45 分後も引き続き表示される場合は、GitHub Enterprise Supportにお問い合わせください。 詳細については、「GitHub Support からのヘルプの受信」を参照してください。

   • それ以外の場合、ghe-repl-status が OK を返さなかった場合は、GitHub Enterprise Supportにお問い合わせください。 詳細については、「GitHub Support からのヘルプの受信」を参照してください。

5. 最後のレプリカのアップグレードが完了し、再同期が完了したら、メンテナンス モードを無効にして、ユーザーが your GitHub Enterprise Server instanceを使用できるようにします。

失敗したアップグレードからのリストア

アップグレードが失敗もしくは中断したなら、インスタンスを以前の状態に復帰させなければなりません。 この処理を完了させるプロセスは、アップグレードの種類によります。

パッチリリースのロールバック

パッチ リリースをロールバックするには、--allow-patch-rollback スイッチを指定して ghe-upgrade コマンドを使用します。 ロールバックする前に、すべてのレプリカ インスタンス上で ghe-repl-stop を実行してレプリケーションを一時的に停止する必要があります。 アップグレードをロールバックする場合は、拡張子が .pkg のアップグレード パッケージ ファイルを使用する必要があります。 拡張子が .hpkg のホットパッチ パッケージ ファイルはサポートされていません。

ghe-upgrade --allow-patch-rollback EARLIER-RELEASE-UPGRADE-PACKAGE.pkg

このコマンドの実行後には再起動が必要です。 パッチリリースでは移行は行われないので、ロールバックはデータパーティションには影響しません。

ロールバックが完了したら、すべてのレプリカ上で ghe-repl-start を実行してレプリケーションを再起動します。

詳細については、「コマンド ライン ユーティリティ」を参照してください。

フィーチャリリースのロールバック

フィーチャリリースからロールバックするには、ルートおよびデータパーティションが整合した状態になることを保証するため、VM スナップショットからリストアしてください。 詳細については、「スナップショットの作成」を参照してください。

参考資料

• "新しいリリースへのアップグレードについて"