Azure DevOps から GitHub Enterprise クラウドへの移行の概要

計画から実装、フォローアップ タスクの完了まで、Azure DevOps から GitHub Enterprise Importer を備えた GitHub への移行プロセス全体を完了する方法について説明します。

この記事の内容

概要

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

Azure DevOps (ADO) から移行する場合、このガイドを使用して移行を計画および実装し、フォローアップ タスクを完了できます。

通常、ADO から GitHub に移行する企業は、複数フェーズのアプローチに従います。

  1. リポジトリを ADO から GitHub に移行する。
  2. パイプラインを Azure Pipelines から GitHub Actions に移行する。
  3. ボードや成果物などの残りの資産を ADO から GitHub に移行する。

このガイドでは、最初のフェーズを完了してリポジトリを GitHub に移行する方法について説明します。なお、ADO2GH extension of the GitHub CLI を使用していることを前提とします。

移行を計画する

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

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

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

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

  • リポジトリの数
  • pull request の数

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

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

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

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

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

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

ADO からの移行の場合、GitHub Enterprise Importer では、pull request や一部のブランチ ポリシーを含む Git リポジトリのみが移行されます。 パイプライン、作業項目、成果物、テスト計画、リリース、ダッシュボードなどのその他の資産は、ADO に残ります。

GitHub と ADO ではアクセス許可の動作が異なるため、GitHub Enterprise Importer は ADO からリポジトリのアクセス許可を移行しようとはしません。 詳しくは、「アクセス許可の構成」を参照してください。

サービス フックは ADO から移行されないため、個別に再作成する必要があります。

  1. Azure DevOps から移行されたデータを確認します。 詳しくは、「Azure DevOps から GitHub Enterprise クラウドへの移行について」を参照してください。
  2. 手動で移行または再作成する必要があるデータの一覧を作成します。

誰が移行を実行するか?

リポジトリを移行するには、移行先の Organization の Organization 所有者であるか、Organization 所有者が移行者ロールを付与する必要があります。

  1. 移行先の Organization の Organization 所有者に移行を実行させるか、移行者ロールを他のユーザーに付与する必要があるかを決定します。
  2. 移行者ロールを付与する場合は、ロールを付与する個人またはチームを決めます。
  3. 移行者ロールを個人またはチームに付与します。 詳しくは、「Azure DevOps からの移行のアクセスの管理」をご覧ください。
  4. ユーザーが、すべてのアクセス要件を満たすように personal access token を正しく構成していることを確認します。詳しくは、「Azure DevOps からの移行のアクセスの管理」をご覧ください。

GitHub ではどんな Organization 構造が必要か?

次に、GitHub で作成する Organization 構造を計画します。 ADO と GitHub には、企業の作業を整理する方法が異なります。

  • ADO: 組織 > チーム プロジェクト > リポジトリ
  • GitHub: Enterprise > Organization > リポジトリ

注: ADO でリポジトリのグループ化に使用されるチーム プロジェクトの概念は、GitHub には存在しません。 GitHub の Organization を、ADO のチーム プロジェクトと同等のものとして扱うことはお勧めしません。

GitHub に移行した後は、Enterprise アカウントを 1 つのみにし、その Enterprise で所有する Organization の数を少なくする必要があります。 ADO の各組織は、GitHub 上の単一の Organization に対応する必要があります。 GitHub で、ADO のチーム プロジェクトごとに Organization を作成することはお勧めしません。

これにより、各 Organization 内のグループ化されていないリポジトリのリストが大きくなる可能性があります。 ただし、チームを作成すると、リポジトリのグループへのアクセスを管理できます。 詳しくは、「Team について」を参照してください。

移行作業をバッチに分割する場合、新しい構造がバッチの決定に役立ちます。 ADO に複数の組織があり、各組織のリポジトリが適切なサイズのバッチである場合は、組織ごとのバッチ処理を検討します。 GitHub CLI を使用して、ADO 上の組織全体の移行スクリプトを生成できます。

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

移行の実行

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

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

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

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

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

  1. 試用版の移行のテスト用 Organization を作成します。
  2. 試験的移行を実行します。
  3. 試験的移行では、以下で説明するフォローアップ タスクを完了します。
  4. 移行の結果を検証するようにユーザーに依頼します。
  5. 試験的移行によって明らかになった問題を解決します。
  6. 移行先で IP 許可リストを使っている場合は、GitHub Enterprise Importer によるアクセスを許可するようにリストを構成します。詳しくは、「Azure DevOps からの移行のアクセスの管理」を参照してください。
  7. 運用移行を実行します。 詳しくは、「Azure DevOps から GitHub Enterprise Cloud へのリポジトリの移行」を参照してください。
  8. 必要に応じて、テスト用の Organization を削除します。

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

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

移行の状態を確認する

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

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

  • 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 を使用した移行のトラブルシューティング」を参照してください。 移行の警告を確認したら、それらの警告を受け入れて先に進むことができるかどうかを決定する必要があります。

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

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

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

アクセス許可の構成

GitHub と ADO ではアクセス許可の動作が異なるため、GitHub Enterprise Importer は ADO からリポジトリのアクセス許可を移行しようとはしません。

ADO2GH CLI を使用した場合、GitHub Enterprise Importer によって、ADO のチーム プロジェクトごとに 2 つのチームが GitHub に作成されます。 各チームには、チーム プロジェクトから作成されたすべてのリポジトリへの異なるレベルのアクセス権が付与されます。

チーム移行されたリポジトリへのアクセス
TEAM-PROJECT-メンテナメンテナ
TEAM-PROJECT-管理者[Admin]

移行されたリポジトリへのアクセス権を付与するには、これらのチームにユーザーを追加します。 これは、GitHub で手動で行うことができます。または、移行中にチームを Azure Active Directory (AAD) グループにリンクすることを選択した場合は、AAD でグループ メンバーシップを管理します。 チーム メンバーシップの手動による管理について詳しくは、「Team への Organization メンバーの追加」を参照してください。

ADO2GH CLI を使用していない場合、またはこの既定よりも高度なアクセス許可構成が必要な場合は、移行したリポジトリのアクセス許可を構成します。 移行スクリプトをニーズに合わせて変更するか、移行後にアクセス許可を手動で構成することができます。 GitHub 上のリポジトリへのアクセスの管理について詳しくは、「Organizationのリポジトリロール」を参照してください。

  1. GitHub で必要なアクセス許可の構造を決定します。
  2. 既定と異なる場合は、チーム メンバーシップとアクセス許可を設定する計画を立てます。

マネキンの回収

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

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

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

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

IP 許可リストの構成

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

詳しくは、「Azure DevOps からの移行のアクセスの管理」を参照してください。