Overview of a migration from Azure DevOps to GitHub Enterprise Cloud

Learn how to complete the entire process of migrating from Azure DevOps to GitHub with GitHub Enterprise Importer, from planning to implementation to completing follow-up tasks.

この記事の内容

Overview

With GitHub Enterprise Importer, you can migrate to GitHub Enterprise Cloud on a repository-by-repository basis. For more information, see GitHub Enterprise Importer について.

If you're migrating from Azure DevOps (ADO), you can use this guide to plan and implement your migration and complete follow-up tasks.

Enterprises who migrate from ADO to GitHub typically follow a multi-phase approach.

  1. Migrate repositories from ADO to GitHub.
  2. Migrate pipelines from Azure Pipelines to GitHub Actions.
  3. Migrate remaining assets, such as boards and artifacts, from ADO to GitHub.

This guide will guide you through completing the first phase, migrating repositories to GitHub, and assumes you're using the ADO2GH extension of the GitHub CLI.

Planning your migration

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

How soon do we need to complete the migration?

Determine your timeline, which will largely dictate your approach. The first step for determining your timeline is to get an inventory of what you need to migrate.

  • Number of repositories
  • Number of pull requests

Migrating from Azure DevOps, we recommend the inventory-report command in the ADO2GH extension of the GitHub CLI. The inventory-report command will connect with the Azure DevOps API, then build a simple CSV with some of the fields suggested above. To install the ADO2GH extension of the GitHub CLI and authenticate, follow steps 1 to 3 in Migrating repositories from Azure DevOps to GitHub Enterprise Cloud.

Migration timing is largely based on the number of pull requests in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests on average, and only 50 users have contributed to the repositories, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 pull requests on average, and 5,000 users, the migration will take much longer and require much more planning and testing.

After you take inventory of the repositories you need to migrate, you can weigh your inventory data against your desired timeline. If your organization can withstand a higher degree of change, then you might be able to migrate all your repositories at once, completing your migration efforts in a few days. However, you may have various teams that are not able to migrate at the same time. In this case, you might want to batch and stagger your migrations to fit the teams' timelines, extending your migration effort.

  1. Determine how many repositories and pull requests you need to migrate.
  2. To understand when teams can be ready to migrate, interview stakeholders.
  3. Fully review the rest of this guide, then decide on a migration timeline.

Do we understand what will be migrated?

Ensure that you and your stakeholders understand what data can be migrated by GitHub Enterprise Importer.

For migrations from ADO, GitHub Enterprise Importer only migrates Git repositories, including pull requests and some branch policies. Any other assets, such as pipelines, work items, artifacts, test plans, releases, and dashboards, will remain in ADO.

Because permissions work differently in GitHub than in ADO, GitHub Enterprise Importer does not attempt to migrate repository permissions from ADO. For more information, see Configuring permissions.

Service hooks are not migrated from ADO, so you will need to recreate them separately.

  1. Review the data that's migrated from Azure DevOps. For more information, see About migrations from Azure DevOps to GitHub Enterprise Cloud.
  2. Make a list of any data that you'll need to manually migrate or recreate.

Who will run the migration?

To migrate a repository, you must be an organization owner for the destination organization, or an organization owner must grant you the migrator role.

  1. Decide whether you want an organization owner of the destination organization to perform your migrations, or whether you need to grant the migrator role to someone else.
  2. 移行者ロールを付与する場合は、ロールを付与する個人またはチームを決めます。
  3. 移行者ロールを個人またはチームに付与します。 For more information, see Managing access for a migration from Azure DevOps.
  4. ユーザーが、すべてのアクセス要件を満たすように personal access token を正しく構成していることを確認します。 For more information, see Managing access for a migration from Azure DevOps.

What organizational structure do we want in GitHub?

Next, plan the organizational structure you'll create in GitHub. ADO and GitHub have different ways of organizing an enterprise's work.

  • ADO: Organization > team project > repositories
  • GitHub: Enterprise > organization > repositories

メモ

The concept of a team project, which is used to group repositories in ADO, does not exist in GitHub. We do not recommend treating organizations in GitHub as the equivalent of team projects in ADO.

After migrating to GitHub, you should have only one enterprise account and a small number of organizations owned by that enterprise. Each organization from ADO should correspond to a single organization on GitHub. We do not recommend creating an organization on GitHub for each team project on ADO.

This may result in a large list of ungrouped repositories within each organization. However, you can manage access to groups of repositories by creating teams. For more information, see Organization のチームについて.

If you want to break your migration effort into batches, the new structure can help you determine your batches. If you have more than one organization in ADO, and each organization's repositories are reasonably sized batches, consider batching by organization. You can use the GitHub CLI to generate a migration script for an entire organization on ADO.

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

Running your migrations

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

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

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

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

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

  1. Create a test organization for your trial migrations.
  2. 試験的移行を実行します。
  3. 試験的移行では、以下で説明するフォローアップ タスクを完了します。
  4. 移行の結果を検証するようにユーザーに依頼します。
  5. 試験的移行によって明らかになった問題を解決します。
  6. 移行先で IP 許可リストを使っている場合は、GitHub Enterprise Importer によるアクセスを許可するようにリストを構成します。 For more information, see Managing access for a migration from Azure DevOps.
  7. Run your production migrations. For more information, see Migrating repositories from Azure DevOps to GitHub Enterprise Cloud.
  8. 必要に応じて、テスト用の Organization を削除します。

Completing follow-up tasks

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

Checking the migration status

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

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

  • GitHub CLI を使用して移行を実行した場合、既定では、移行が完了すると移行が成功したか失敗したかがプロセスにより表示されます。 移行が失敗した場合は、失敗の理由が表示されます。

    Migration completed (ID: RM_123)! State: SUCCEEDED

  • オプションの --queue-only 引数を使用して GitHub CLI により移行を実行した場合、プロセスは移行がキューに登録されるとすぐに終了し、移行が成功したか失敗したかは通知されません。 wait-for-migration コマンドを使用するか、移行ログを確認して、移行の状態をチェックできます。

  • GraphQL API を使用して移行を実行した場合は、RepositoryMigration オブジェクトの state フィールドと failureReason フィールドのクエリを実行できます。

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

Reviewing the migration log

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

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

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

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

Setting repository visibility

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

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

Configuring permissions

Because permissions work differently in GitHub than in ADO, GitHub Enterprise Importer does not attempt to migrate repository permissions from ADO.

If you used the ADO2GH CLI, GitHub Enterprise Importer will create two teams in GitHub for each team project in ADO. Each team is granted a different level of access to all repositories that originated from the team project.

TeamAccess to migrated repositories
TEAM-PROJECT-MaintainersMaintainer
TEAM-PROJECT-AdminsAdmin

To give access to migrated repositories, you can add people to these teams. You can do this manually on GitHub, or if you chose to link the teams to Azure Active Directory (AAD) groups during your migration, by managing group membership in AAD. For more information about manually managing team membership, see Team への Organization メンバーの追加.

If you aren't using the ADO2GH CLI, or if you require a permissions configuration that is more advanced than this default, configure permissions for your migrated repositories. You can modify the migration script to suit your needs, or you can manually configure permissions after your migration. For more information about managing access to repositories on GitHub, see Organizationのリポジトリロール.

  1. Decide what permissions structure you require in GitHub.
  2. If different than the default, make a plan for setting up team membership and permissions.

Reclaiming mannequins

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

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

メモ

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

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

Configuring IP allow lists

If you added the IP ranges for GitHub Enterprise Importer to the IP allow list for your destination organization, you can remove those entries. 移行先 Enterprise に対する ID プロバイダーの IP 許可リスト制限を無効にした場合は、ここでもう一度有効にできます。

For more information, see Managing access for a migration from Azure DevOps.