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

GitHub Enterprise Server へのアップグレードについて

GitHub Enterprise Server は常に改善されており、機能とパッチのリリースによって新機能とバグ修正が導入されています。インスタンスへのアップグレードは自身の責任で行ってください。詳しくは、「新しいリリースへのアップグレードについて」を参照してください。

インスタンスをアップグレードするには、アップグレードの計画と通知、適切なパッケージの選択、データのバックアップ、アップグレードの実行が必要になります。

前提条件

お使いの GitHub Enterprise Server インスタンスを正常にアップグレードするには、インスタンスのデータディスクの空き容量が 15% 以上である必要があります。 GitHub では、ディスク上により多くの空き記憶域があることを確認することが推奨されます。まれに、データ量が多いお客様の場合、このしきい値が異なることがあります。

アップグレードの準備

アップグレードを準備するには、アップグレードパスを計画し、必要に応じて GitHub Actions ランナーをアップグレードし、メンテナンス期間をスケジュールします。

アップグレードの戦略を決定し、アップグレード先のバージョンを選択してください。詳しくは、「アップグレードの要求事項」をご覧ください。また、「Upgrade Assistant」を参照し、現在のリリースバージョンからのアップグレードパスを見つけてください。
GitHub Enterprise Server Backup Utilities で、インスタンスのプライマリノードの新しいバックアップを作成します。詳しくは、GitHub Enterprise Server Backup Utilities プロジェクトドキュメントの README を参照してください。

注: GitHub Enterprise Server Backup Utilities バージョンは、お使いの GitHub Enterprise Server インスタンスと同じバージョンであるか、最大で 2 つ前のバージョンである必要があります。詳しくは、「アプライアンスでのバックアップの設定」を参照してください。
お使いの GitHub Enterprise Server インスタンスが GitHub Actions にエフェメラルセルフホステッドランナーを使っていて、自動更新を無効にしている場合、アップグレードされたインスタンスが実行するランナーアプリケーションのバージョンにランナーをアップグレードしてください。
アップグレードパッケージを使ってアップグレードをする場合は、GitHub Enterprise Server のエンドユーザのためにメンテナンス時間枠をスケジューリングしてください。ホットパッチを利用している場合、メンテナンスモードは必要ありません。

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

スナップショットの取得

スナップショットには、ある時点での仮想マシン (VM) の状態が格納されます。 GitHub では、アップグレードに失敗した場合に VM をスナップショットに戻せるように、VM をアップグレードする前にスナップショットを作成しておくことが強く推奨されます。 GitHub では、インスタンスの VM の電源が切れているか、インスタンスがメンテナンスモードであり、すべてのバックグラウンドジョブが完了している場合にのみ、VM スナップショットを作成することが推奨されます。

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

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

VM スナップショットは、ユーザーデータと構成データを含む VM の状態全体を保存します。このスナップショットの手法には大量のディスク領域が必要になり、時間がかかります。
データディスクスナップショットは、ユーザーデータのみを保存します。
注:
- プラットフォームによっては、ユーザのデータディスクだけのスナップショットを取ることができません。それらのプラットフォームでは、VM 全体のスナップショットを取る必要があります。
- ハイパーバイザーが完全なVMスナップショットをサポートしていないなら、ルートディスクとデータディスクのスナップショットを時間をおかずに取らなければなりません。

プラットフォーム	Snapshot メソッド	ドキュメント
Amazon AWS	ディスク	AWS ドキュメントの「Amazon EBS スナップショットの作成」
Azure	VM	Microsoft Learn の「VM の設定から Azure VM をバックアップする」
Hyper-V	VM	Microsoft Learn の「Hyper-V でチェックポイントを有効または無効にする」
Google Compute Engine	ディスク	Google Cloud ドキュメントの「ディスクスナップショットを作成して管理する」
VMware	VM	VMware Docs の「Taking Snapshots of a Virtual Machine (仮想マシンのスナップショットの作成)」

アップグレードパッケージの選択

GitHub Enterprise Server インスタンスを新しいパッチリリースまたは新しい機能リリースにアップグレードできます。パッチリリースにアップグレードするために、ホットパッチまたはアップグレードパッケージを使用できます。機能リリースにアップグレードするには、アップグレードパッケージを使用する必要があります。

GitHub Enterprise Server インスタンスは、1 つまたは複数のノードで構成されます。従う必要があるアップグレードプロセスは、インスタンスに含まれるノードの数によって異なります。詳しくは、「GitHub Enterprise Server について」を参照してください。

ホットパッチでのアップグレード
- ホットパッチを使用したスタンドアロンインスタンスのアップグレード
- ホットパッチを使用した複数のノードを持つインスタンスのアップグレード
アップグレードパッケージでのアップグレード
- アップグレードパッケージを使用したスタンドアロンインスタンスのアップグレード
- アップグレードパッケージを使用した複数のノードを持つインスタンスのアップグレード

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

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

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

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

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

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

注:

お使いの GitHub Enterprise Server インスタンスによってリリース候補ビルドが実行されている場合、ホットパッチを使ったアップグレードはできません。
クラスターでは、[Management Console]を使ってホットパッチをインストールすることはできません。クラスターのホットパッチをインストールする場合は、「クラスタのアップグレード」を参照してください。

ホットパッチを使用したスタンドアロンインスタンスのアップグレード
ホットパッチを使用した複数のノードを持つインスタンスのアップグレード

ホットパッチを使用したスタンドアロンインスタンスのアップグレード

ホットパッチを使用して 1 つのノードを持つインスタンスをアップグレードしており、ターゲットがパッチリリースである場合は、[Management Console]を使ってアップグレードできます。機能のリリースにアップグレードするには、管理シェルを使用する必要があります。

[Management Console] を使ってホットパッチをインストールする
管理シェルを使ったホットパッチのインストール

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

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

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

自動更新を有効にする。詳しくは、「自動アップデートチェックの有効化」を参照してください。
GitHub Enterprise Server の管理アカウントから、任意のページの右上隅でをクリックします。
[サイト管理者] ページにまだ表示されていない場合は、左上隅の [サイト管理者] をクリックします。 1. [ サイト管理者] サイドバーで [Management Console] をクリックします。 1. 上部のナビゲーションバーで [更新プログラム] をクリックします。
新しいホットパッチがダウンロードされている場合、 [パッケージのインストール] ドロップダウンメニューを選択します。
- すぐにインストールするには、 [今すぐ] をクリックします。
- 後でインストールするなら、後の日付を選択してください。
[インストール] をクリックします。

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

注: 自動更新チェックを有効にすると、アップグレードパッケージをダウンロードする必要はなく、自動的にダウンロードされたファイルを利用できます。詳しくは、「自動アップデートチェックの有効化」を参照してください。

お使いの GitHub Enterprise Server インスタンスに SSH で接続します。インスタンスが複数のノードで構成されている場合は (高可用性や geo レプリケーションが構成されている場合など)、プライマリノードに SSH 接続します。クラスターを使用する場合は、任意のノードに SSH 接続できます。 SSH アクセスについて詳しくは、「管理シェル (SSH) にアクセスする」をご覧ください。
```
$ ssh -p 122 admin@HOSTNAME
```
GitHub Enterprise Server リリースページを参照します。アップグレード先対象リリースの横にある [ダウンロード] をクリックし、 [アップグレード] タブをクリックします。アップグレードのホットパッケージ ( .hpkg ファイル) の URL をコピーします。
curl を使って、アップグレードパッケージをお使いの GitHub Enterprise Server インスタンスにダウンロードします。
```
admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL
```
このパッケージファイル名を使って ghe-upgrade コマンドを実行します。
```
admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.hpkg
*** verifying upgrade package signature...
```
少なくとも 1 つのサービスまたはシステムコンポーネントで再起動が必要な場合は、ホットパッチアップグレードスクリプトによって通知されます。たとえば、カーネル、MySQL、Elasticsearch の更新には再起動が必要な場合があります。

ホットパッチを使用した複数のノードを持つインスタンスのアップグレード

ホットパッチをインストールする場合、メンテナンスモードに切り替えたり、レプリケーションを停止したりする必要はありません。

ホットパッチを使用したプライマリノードのアップグレード
ホットパッチを使用した追加ノードのアップグレード

ホットパッチを使用したプライマリノードのアップグレード

プライマリノードをアップグレードする手順については、「管理シェルを使ったホットパッチのインストール」を参照してください。

ホットパッチを使用した追加ノードのアップグレード

高可用性や geo レプリケーション構成など、複数のノードから構成されるインスタンスをアップグレードするには、レプリカノードごとに、一度に 1 つずつ、次の手順を繰り返す必要があります。

ノードをアップグレードするには、「管理シェルを使ったホットパッチのインストール」の手順に従います。
ポート 122 の SSH 経由でレプリカノードに admin ユーザーとして接続します。
```
$ ssh -p 122 admin@REPLICA_HOST
```
1. 以下を実行して、アップグレードを検証してください。
```
$ ghe-version
```
1. 追加ノードごとに上記の手順を繰り返します。

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

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

アップグレードパッケージを使用したスタンドアロンインスタンスのアップグレード
アップグレードパッケージを使用した複数のノードを持つインスタンスのアップグレード

アップグレードパッケージを使用したスタンドアロンインスタンスのアップグレード

注: 自動更新チェックを有効にすると、アップグレードパッケージをダウンロードする必要はなく、自動的にダウンロードされたファイルを利用できます。詳しくは、「自動アップデートチェックの有効化」を参照してください。

お使いの GitHub Enterprise Server インスタンスに SSH で接続します。インスタンスが複数のノードで構成されている場合は (高可用性や geo レプリケーションが構成されている場合など)、プライマリノードに SSH 接続します。クラスターを使用する場合は、任意のノードに SSH 接続できます。 SSH アクセスについて詳しくは、「管理シェル (SSH) にアクセスする」をご覧ください。
```
$ ssh -p 122 admin@HOSTNAME
```
GitHub Enterprise Server リリースページを参照します。アップグレード先対象リリースの横にある [ダウンロード] をクリックし、 [アップグレード] タブをクリックします。適切なプラットフォームを選び、アップグレードパッケージ ( .pkg fファイル) の URL をコピーします。
curl を使って、アップグレードパッケージをお使いの GitHub Enterprise Server インスタンスにダウンロードします。
```
admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL
```
メンテナンスモードを有効にし、GitHub Enterprise Server インスタンス上のすべてのアクティブなプロセスが完了するのを待ってください。詳しくは、「メンテナンスモードの有効化とスケジューリング」を参照してください。

注: 「プライマリノードのアップグレード」の手順に従っている場合、高可用性構成のプライマリノードをアップグレードするときにインスタンスは既にメンテナンスモードになっているはずです。
このパッケージファイル名を使って ghe-upgrade コマンドを実行します。
```
admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.pkg
*** verifying upgrade package signature...
```
アップグレードを続けてパッケージ署名検証後に再起動することを承諾します。新しいルートファイルシステムがセカンダリパーティションに書かれ、インスタンスは自動的にメンテナンスモードで再起動します。
```
*** 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]
```
必要に応じて復元を検証するには、IP アドレスの指定リストへのアクセスを許可するように IP 例外リストを構成します。詳しくは、「メンテナンスモードの有効化とスケジューリング」を参照してください。
単一ノードのアップグレードの場合は、メンテナンスモードを無効にして、ユーザーがお使いの GitHub Enterprise Server インスタンスを使用できるようにします。

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

アップグレードパッケージを使用した複数のノードを持つインスタンスのアップグレード

アップグレードパッケージを使用して複数のノードで構成されるインスタンスをアップグレードするには、プライマリノードをアップグレードしてから、追加のノードをアップグレードする必要があります。

アップグレードパッケージでのプライマリノードのアップグレード
アップグレードパッケージでの追加ノードのアップグレード

アップグレードパッケージでのプライマリノードのアップグレード

警告: レプリケーションを停止したときにプライマリに障害が発生した場合、レプリカをアップグレードしてレプリケーションを再開する前に行った作業内容は失われます。

プライマリノードでメンテナンスモードを有効にし、すべてのアクティブなプロセスが完了するのを待ちます。詳しくは、「メンテナンスモードの有効化とスケジューリング」を参照してください。
ポート 122 の SSH 経由でレプリカノードに admin ユーザーとして接続します。
```
$ ssh -p 122 admin@REPLICA_HOST
```
すべてのノードでレプリケーションを停止するには、各ノードで ghe-repl-stop を実行します。
プライマリノードをアップグレードするには、「アップグレードパッケージを使用したスタンドアロンインスタンスのアップグレード」の手順に従います。

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

高可用性や geo レプリケーション構成など、複数のノードから構成されるインスタンスをアップグレードするには、レプリカノードごとに、一度に 1 つずつ、次の手順を繰り返す必要があります。

「アップグレードパッケージを使用したスタンドアロンインスタンスのアップグレード」の手順に従って、プライマリノードをアップグレードします。
ポート 122 の SSH 経由でレプリカノードに admin ユーザーとして接続します。
```
$ ssh -p 122 admin@REPLICA_HOST
```
1. 以下を実行して、アップグレードを検証してください。
```
$ ghe-version
```
1. レプリカノードでレプリケーションを開始するには、`ghe-repl-start` を実行します。1. レプリカノードで、レプリケーションサービスが正しく動作していることを確認するには、`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 サポートにお問い合わせください。詳しくは、「GitHub Support へのお問い合わせ」を参照してください。
それ以外の場合、ghe-repl-status が OK を返さなかった場合は、GitHub Enterprise サポートにお問い合わせください。詳しくは、「GitHub Support へのお問い合わせ」を参照してください。

追加ノードごとに上記の手順を繰り返します。
最後のレプリカノードをアップグレードし、再同期が完了した後、メンテナンスモードを無効にして、ユーザーがお使いの GitHub Enterprise Server インスタンスを使用できるようにします。

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

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

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

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

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

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

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

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

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

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

参考資料

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

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

この記事の内容