GitHub 製品間の移行に関する概要

概要

GitHub Enterprise Importer を使用すると、GitHub Enterprise Cloud に移行できます。詳細については、「GitHub Enterprise Importer について」を参照してください。

GitHub Enterprise Server から GitHub Enterprise Cloud へなど、GitHub 製品間で移行する場合は、このガイドを使って移行を計画して実装し、フォローアップタスクを完了できます。サポートされている移行パスの完全な一覧については、「GitHub Enterprise Importer について」を参照してください。

移行を計画する

移行を計画するには、次の質問に対する答えを考えてください。

Organization 単位で移行するか、またはリポジトリ単位か?
どのくらいで移行を完了する必要があるか?
何が移行されるかを理解しているか?
誰が移行を実行するか?
移行後も同様の Organization 構造を維持するか?

Organization 単位で移行するか、またはリポジトリ単位か?

まず、移行元と移行先がどちらも GitHub.com である場合は、Organization 単位で移行するか、またはリポジトリ単位で移行するかを決めます。

メモ: GitHub Enterprise Server から移行する場合は、リポジトリのみを移行できます。

リポジトリ単位の移行を選んだ場合、リポジトリレベルのデータのみが移行されます。 Organization 単位の移行戦略を選んだ場合は、選択した Organization レベルのデータも移行されます。これにはチームとそのリポジトリアクセス権が含まれます。

ただし、Organization を移行するときは、移行元の Organization が所有するすべてのリポジトリが同時に移行されます。リポジトリをバッチに分割することや、Organization のいずれかのリポジトリについて移行をスキップすることはできません。多数のリポジトリがある場合、またはすべてのリポジトリのダウンタイムを同時に許容できない場合は、代わりにリポジトリの移行を実行することが必要になります。

さらに、Organization の移行により、移行先の Enterprise アカウントに新しい Organization が作成されます。リポジトリを既存の Organization に移行する場合は、代わりにリポジトリの移行を実行することが必要になります。

最後に、Organization を移行するには、移行先の Enterprise アカウントの Enterprise 所有者である必要があります。 Enterprise 所有者ではないユーザーを移行タスクの実行者にする場合は、リポジトリの移行を実行する必要があります。

どのくらいで移行を完了する必要があるか?

タイムラインを決定します。これによって、アプローチが大きく異なります。タイムラインを決定するための最初の手順は、移行する必要があるもののインベントリを取得することです。このデータを収集するには、GitHub CLI のgh-repo-stats拡張機能を使用します。このオープンソースツールは、Organization について移行するデータの量を詳しく示すレポートを生成します。

注: gh-repo-stats はサードパーティ製のオープンソースツールであり、GitHub サポートではサポートされません。このツールについてヘルプが必要な場合は、そのリポジトリで issue を開いてください。

リポジトリの数
pull request の数
問題の数
ユーザーの数
プロジェクトと Wiki の使用状況

移行の所要時間は、主にリポジトリ内の pull request と issue の数に基づきます。 1,000 個のリポジトリを移行する必要があり、各リポジトリには平均で 100 個の pull request と issue があり、リポジトリに貢献したユーザーが 50 人だけである場合、移行は非常に迅速に完了する可能性があります。移行する必要があるリポジトリは 100 個であるが、各リポジトリに平均で 75,000 個の pull request と issue があり、5,000 人のユーザーがいる場合、移行にかかる時間は長くなり、必要な計画とテストもはるかに多くなります。

アナライザーを使った後は、インベントリデータを目的のタイムラインと比較検討できます。組織がより高度な変更に耐えられる場合、すべてのリポジトリを一度に移行して、移行作業を数日で完了できる可能性があります。しかし、さまざまなチームがあり、それらを同時に移行できない場合もあります。このような場合、チームのタイムラインに合わせて移行をバッチ処理し、移行が重ならないように調整できますが、移行作業の期間は長くなります。

GitHub CLI のgh-repo-stats拡張機能を使用し、移行インベントリを確認します。
チームの移行の準備が整うタイミングを把握するには、関係者にインタビューします。
このガイドの残りの部分を完全に確認してから、移行のタイムラインを決定してください。

注: gh-repo-stats はサードパーティ製のオープンソースツールであり、GitHub サポートではサポートされません。このツールについてヘルプが必要な場合は、そのリポジトリで issue を開いてください。

何が移行されるかを理解しているか?

GitHub Enterprise Importer によって移行できるデータを自分と関係者が理解していることを確認します。

移行元の移行されるデータを確認します。詳しくは、「GitHub 製品間の移行について」を参照してください。
手動で移行または再作成する必要があるデータの一覧を作成します。

誰が移行を実行するか?

誰が移行を実行するかを決定し、この人物が必要なアクセス権を持っていることを確認します。オプションは、Organization 単位で移行するか、リポジトリ単位で移行するかによって異なります。

誰が Organization の移行を実行するかを決める

Organization を移行するには、移行元 Organization の Organization 所有者であるか、Organization 所有者からその Organization の移行者ロールを付与される必要があります。

また、移行先 Enterprise アカウントの Enterprise 所有者である必要があります。 Enterprise アカウントに移行者ロールを付与することはできません。

移行を実行する人物が、移行先 Enterprise アカウントの Enterprise 所有者であることを確認します。
その人物が移行元 Organization の Organization 所有者でない場合は、Organization の移行者ロールを付与します。詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
ユーザーが、すべてのアクセス要件を満たすように personal access token を正しく構成していることを確認します。詳しくは、「GitHub 製品間の移行のためのアクセスの管理」をご覧ください。

誰がリポジトリの移行を実行するかを決める

リポジトリを移行するには、移行元 Organization と移行先 Organization の両方の Organization 所有者である必要があります。または、Organization 所有者から、所有者ではない各 Organization の移行者ロールを付与される必要があります。

Organization 所有者に移行を実行させるか、移行者ロールを他のユーザーに付与する必要があるかを決定します。
移行者ロールを付与する場合は、ロールを付与する個人またはチームを決めます。
移行者ロールを個人またはチームに付与します。詳しくは、「GitHub 製品間の移行のためのアクセスの管理」をご覧ください。

メモ: 移行元 Organization と移行先 Organization の両方に移行者ロールを付与することを忘れないでください。
ユーザーが、すべてのアクセス要件を満たすように personal access token を正しく構成していることを確認します。詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。

移行後も同様の Organization 構造を維持するか?

次に、移行後も同様の Organization 構造を維持するかどうかを検討します。これは、移行作業をバッチに分割する場合にバッチを決定するのに役立ちます。移行元と移行先の Organization 間で一対一の対応を維持する場合は、Organization 単位で移行をバッチ処理することをお勧めします。これは最も簡単な方法です。特に、GitHub.com から移行する場合は、1 つのコマンドで Organization 全体を移行できるためです。別の移行元から移行する場合は、GitHub CLI で、1 つの Organization 内のすべてのリポジトリを移行するスクリプトを生成できます。

Organization 構造を変更する場合は、他のバッチ処理の要素を検討してください。類似のチームやビジネス部門が所有するリポジトリをバッチ処理することや、移行先 Organization 単位でバッチ処理することができます。可能であれば、チーム単位でバッチ処理することをお勧めします。事業部門または移行先 Organization 単位でバッチ処理すると、関わる関係者の数が増え、移行の時間枠が短くなる可能性があります。

Organization 構造を変更する場合でも、移行のためのスクリプトを準備できます。 GitHub CLI コマンドを使用し、必要に応じて各リポジトリの行を異なるスクリプトに移動します。

メモ: 複数のバッチを同時に実行できます。たとえば、チーム単位でバッチ処理する場合は、複数のチームの移行を同じ時間枠内に実行できます。

新しい Organization の構造を決めます。
移行作業を小さいバッチに分割する必要があるかどうかを決めます。
そうする場合は、移行の分割方法を決めます。

移行の実行

計画が完了したら、実際の移行を開始できます。自分の Enterprise に固有の、移行中および移行後の問題を明らかにするため、すべての移行の試験的実行を行うことを強くお勧めします。試験的実行で明らかになった問題を解決した後、運用環境の移行を実行できます。

試験的移行は、いくつかの重要な情報を特定するのに役立ちます。

特定のリポジトリの移行を正常に完了できるかどうか
ユーザーが正常に作業を開始できる状態に、リポジトリを戻すことができるかどうか
移行の実行にかかる時間。これは、移行のスケジュールを計画し、利害関係者の期待を設定するのに役立ちます

試験的実行に多くの時間をかける必要はありません。 GitHub Enterprise Importer では、移行対象のリポジトリのユーザーにダウンタイムは必要ありません。ただし、運用環境の移行の間は、移行中に新しいデータが作成されないようにするため、作業を停止することをお勧めします。作成されたものは、移行されたリポジトリに含まれません。試験的移行にはこのような問題はないので、試験的実行はいつでも行うことができます。試験的移行の完了にかかる時間を短縮するには、試験的実行のバッチを連続してスケジュールできます。それらのリポジトリのユーザーは、都合のよいときに結果を検証できます。

リポジトリの移行の場合は、試験的な移行の移行先として使用するテスト用 Organization を作成することをお勧めします。すべての試験的実行に 1 つの Organization を使うことも、目的の移行先 Organization ごとに 1 つのテスト Organization を作成することもできます。 Organization が移行検証のみを目的としており、運用環境向けではないことを明確にするために、Organization 名の末尾に -sandbox を含めることを検討してください。終わったら、テスト Organization を削除してかまいません。

リポジトリの移行を実行する場合は、試験的な移行のためのテスト用 Organization を作成します。
移行元 Organization で IP 許可リストを使用している場合は、GitHub Enterprise Importer によるアクセスを許可するようにリストを構成します。詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
試験的移行を実行します。
試験的移行では、以下で説明するフォローアップタスクを完了します。
移行の結果を検証するようにユーザーに依頼します。
試験的移行によって明らかになった問題を解決します。
移行先で IP 許可リストを使っている場合は、GitHub Enterprise Importer によるアクセスを許可するようにリストを構成します。詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
リポジトリの移行を実行していて、GitHub Advanced Security 設定を移行する場合は、移行先 Organization に対して GitHub Advanced Security を有効にします。詳しくは、「組織のセキュリティおよび分析設定を管理する」を参照してください。
運用移行を実行します。詳細については、「GitHub Enterprise Importer について」または「GitHub.com から GitHub Enterprise Cloud へのリポジトリの移行」を参照してください。
必要に応じて、テスト用の Organization を削除します。

フォローアップタスクの完了

各移行が完了したら、リポジトリが機能する状態になる前に、いくつかの追加タスクを完了する必要があります。

移行の状態を確認する
移行ログの確認
Git LFS オブジェクトの移行
リポジトリの可視性を設定する
GitHub Actions の構成
IP 許可リストの構成
GitHub Advanced Securityの管理
Webhook の有効化
GitHub Apps の再インストール
チームの再作成
マネキンの回収

移行の状態を確認する

まず、移行が成功したか失敗したかをチェックします。

移行の状態をチェックする方法は、移行の実行方法によって異なります。

GitHub CLI を使用して移行を実行した場合、既定では、移行が完了すると移行が成功したか失敗したかがプロセスにより表示されます。移行が失敗した場合は、失敗の理由が表示されます。
```
Migration completed (ID: RM_123)! State: SUCCEEDED
```
オプションの --queue-only 引数を使用して GitHub CLI により移行を実行した場合、プロセスは移行がキューに登録されるとすぐに終了し、移行が成功したか失敗したかは通知されません。 wait-for-migration コマンドを使用するか、移行ログを確認して、移行の状態をチェックできます。
GraphQL API を使用して移行を実行した場合は、RepositoryMigration オブジェクトの state フィールドと failureReason フィールドのクエリを実行できます。

移行が失敗した場合、移行ログに失敗の原因に関する追加情報がある可能性があります。詳細については、「移行ログの確認」を参照してください。

移行ログの確認

移行された各リポジトリの移行ログを確認します。詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。

移行が失敗した場合、ログに失敗の原因に関する追加情報がある可能性があります。

移行が成功した場合、移行されていないまたは警告付きで移行された特定のデータの部分 (pull request、イシュー、コメントなど) を表す警告が移行ログに含まれている場合があります。

移行の警告の詳細については、「GitHub Enterprise Importer を使用した移行のトラブルシューティング」を参照してください。移行の警告を確認したら、それらの警告を受け入れて先に進むことができるかどうかを決定する必要があります。

Git LFS オブジェクトの移行

GitHub Enterprise Importer で Git LFS オブジェクトは移行されません。移行元リポジトリで Git LFS を使用している場合は、移行されたリポジトリに Git LFS オブジェクトを手動でローカルにプッシュできます。詳しくは、「リポジトリを複製する」を参照してください。

リポジトリの可視性を設定する

すべてのリポジトリは、既定ではプライベートとして移行され、移行を実行したユーザーと組織の所有者のみが、リポジトリにアクセスできます。リポジトリをプライベートにしたくない場合は、可視性を変更します。

--target-repo-visibility CLI オプションまたは targetRepoVisibility GraphQL プロパティを使用して、リポジトリの表示範囲を設定できます。
リポジトリの可視性はブラウザーで変更できます。詳しくは、「リポジトリの可視性を設定する」を参照してください。
または、GitHub CLI を使って、コマンドラインからリポジトリの可視性を変更することもできます。移行を実行するために生成されたスクリプトに、このコマンドを追加することもできます。詳細については、GitHub CLI ドキュメントの「gh repo edit」を参照してください。

GitHub Actions の構成

リポジトリで GitHub Actions を使用すると、ワークフローは Git リポジトリの一部として自動的に移行されます。

移行プロセス中、ワークフローが誤ってトリガーされないように、移行されたすべてのリポジトリに対して GitHub Actions が無効になりますが、移行が完了すると GitHub Actions が再び有効になります。

より大きなランナーセルフホステッドランナーまたは暗号化されたシークレットを使用していた場合は、それらを再構成する必要があります。

メモ: GitHub Actions のワークフロー実行履歴は移行に含まれません。

セルフホステッドランナーを使用する場合は、ランナーを再構成します。
- 適切なリポジトリ、Organization、または Enterprise にランナーを追加します。詳しくは、「自己ホストランナーの追加」を参照してください。
- Organization または Enterprise レベルでランナーを使用するには、ワークフローを更新します。詳しくは、「ワークフローでのセルフホストランナーの利用」を参照してください。
より大きなランナーを使用する場合は、ランナーを再構成します。
- ランナーグループを設定し、ランナーへのアクセスを制御します。詳しくは、「より大きなランナーへのアクセスの制御」を参照してください。
- より大きなランナーの設定します。詳しくは、「より大きなランナーを管理する」を参照してください。
- ランナーを指すワークフローを更新します。詳しくは、「より大きなランナーでジョブを実行する」を参照してください。
暗号化シークレットがあればもう一度追加します。
- ブラウザーを使用するには、「GitHub Actions でのシークレットの使用」を参照してください。
- GitHub CLI を使用するには、GitHub CLI ドキュメントの「gh secret」を参照してください。
環境を再構成します。詳しくは、「デプロイに環境の使用」を参照してください。

IP 許可リストの構成

GitHub Enterprise Importer の IP 範囲を移行元または移行先 Organization の IP 許可リストに追加した場合は、それらのエントリを削除できます。移行先 Enterprise に対する ID プロバイダーの IP 許可リスト制限を無効にした場合は、ここでもう一度有効にできます。

詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。

GitHub Advanced Securityの管理

リポジトリを移行する前に移行先 Organization に対して GitHub Advanced Security を有効にした場合、個々の機能の設定は移行されています。そうでない場合は、移行後に個々の機能をもう一度有効にする必要があります。詳しくは、「リポジトリのセキュリティと分析設定を管理する」を参照してください。

各機能には、移行後の追加手順があります。

Secret scanning

移行先リポジトリに対してシークレットスキャンが有効になっている場合は、リポジトリ全体のスキャンが実行されます。スキャンが完了すると、すべてのアラートが取り込まれますが、修復の状態は含まれません。

REST API を使用してアラートを更新し、移行元リポジトリでのすべての修復をミラーリングできます。詳しくは、「シークレットスキャン用の REST API エンドポイント」を参照してください。

これらの更新された修復に関連付けられているユーザーは、移行元リポジトリのアラートを修復したユーザーではなく、API 呼び出しに使用された personal access token を所有するユーザーであり、修復に関連付けられた日付は、移行元リポジトリでアラートが修復された日付ではなく、API 呼び出しの日付になります。

Code scanning

Code scanning のアラートは、GitHub Enterprise Importer で移行されません。ただし、アラートは移行元リポジトリの SARIF データとして使用できます。 REST API を使用して、このデータを移行先リポジトリにアップロードできます。詳しくは、「コードスキャン用の REST API エンドポイント」を参照してください。

この方法で取り込まれた Code scanning アラートは、移行元リポジトリ内の元のアラートとは異なります。

アラートには、移行元リポジトリからのタイムライン全体ではなく、アラートの検出と最新の状態のみが含まれます。
アラートは、open または fixed としてのみ識別されます。 dismissed や reopened など、その他の修復状態は失われます。
アラートのすべてのイベントの日付は、移行元リポジトリでイベントが最初に発生した日付ではなく、API 呼び出しの日付になります。
アラート作成者などのすべてのアクターは、API 呼び出しに使用される personal access token の所有者に変更されます。

Dependabot alerts

Dependabot alerts と依存関係グラフが有効になっている場合、Dependabot alerts は既定のブランチの現在の状態から再構築されます。これらのアラートの修復状態は移行されず、以前のアラートも移行されません。

Dependabot の暗号化されたシークレットがあれば再追加する必要があります。詳しくは、「Dependabot のプライベートレジストリへのアクセスの構成」を参照してください。

Webhook の有効化

移行元リポジトリ内のすべてのアクティブな Webhook が移行されます。ただし、移行された Webhook は既定で無効になります。これらの Webhook は、リポジトリ設定で再び有効にすることができます。

移行されたリポジトリの設定に移動します。
サイドバーの [コードと自動化] セクションで、 [Webhook] をクリックします。
有効にする Webhook の右側にある [編集] をクリックします。
シークレットトークンを使用して Webhook をセキュリティで保護していた場合は、[シークレット] でシークレットを再追加します。
ページの下部にある [アクティブ] を選びます。
[Webhook の更新] をクリックします。

GitHub Apps の再インストール

移行元リポジトリに GitHub Apps がインストールされていた場合は、移行されたリポジトリに再インストールする必要があります。詳しくは、「独自の GitHub App のインストール」を参照してください。

チームの再作成

Organization 単位で移行した場合、必要なのはチームメンバーシップを復帰させることだけです。リポジトリ単位で移行した場合は、チームを再作成し、それらのチームにリポジトリへのアクセス権を付与してから、チームメンバーシップを復帰させる必要があります。

Organization 移行の場合のチームの再作成

チームとそのリポジトリアクセス権は、Organization の移行の一部として移行されますが、チームメンバーシップは移行されません。移行後、移行したチームにユーザーを追加する必要があります。

ID プロバイダー (IdP) でチーム同期を使用してチームメンバーシップを管理することを強くお勧めします。詳しくは、「Overview of a migration between GitHub products」、または Enterprise Managed Users を使用しない Enterprise の場合は、「Enterprise で Organization の Team 同期を管理する」を参照してください。

それ以外の場合は、Organization にメンバーを手動で追加してから、Organization のメンバーをチームに追加できます。詳しくは、「Team への Organization メンバーの追加」を参照してください。

リポジトリ移行の場合のチームの再作成

チームはリポジトリ移行の一部として移行されません。チームを手動で再作成し、各チームにリポジトリへのアクセス権を付与する必要があります。

チームを再作成します。詳しくは、「Team の作成」を参照してください。
Organization メンバーをチームに追加します。詳しくは、「Team への Organization メンバーの追加」を参照してください。
各チームにリポジトリへのアクセス権を付与します。詳しくは、「Organization のリポジトリに対するチームのアクセスを管理する」を参照してください。

マネキンの回収

GitHub Enterprise Importer を使って移行を実行した後、移行されたリポジトリでのすべてのユーザーアクティビティ (Git コミットを除く) は、マネキンと呼ばれるプレースホルダー ID に帰属します。

GitHub CLI またはブラウザーを使用して、各マネキンの履歴を組織のメンバーにもう一度帰属させることができます。 GitHub CLI を使う場合は、マネキンを一括して回収できます。詳しくは、「GitHub Enterprise Importer のマネキンの回収」をご覧ください。

注: マネキンを回収できるのは Organization の所有者だけです。移行者ロールが付与されているユーザーは、Organization 所有者にこのステップの実行を依頼してください。

マネキンを回収するかどうかを決めます。
いつ回収を完了するかを計画します。
マネキンを回収します。
チームメンバーシップを介してリポジトリへの適切なアクセス権をまだ持っていないメンバーがいる場合は、そのメンバーにリポジトリへのアクセス権を付与します。詳しくは、「Organization のリポジトリへの個人のアクセスを管理する」を参照してください。

GitHub 製品間の移行に関する概要

この記事の内容