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 关于组织团队.

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. 决定新组织结构。
  2. 决定是否需要将迁移工作分解成更小的批次。
  3. 如果需要，请决定要如何分解迁移。

Running your migrations

完成规划后，可以开始实际迁移。 为了帮助发现迁移期间和迁移后企业可能特有的问题，强烈建议对所有迁移执行试运行。 解决试运行发现的任何问题后，可以运行生产迁移。

试迁移有助于确定几个关键信息。

  • 给定存储库的迁移是否可以成功完成
  • 是否可以将存储库恢复为用户可以成功开始工作的状态
  • 运行迁移所需的时间，这对于规划迁移计划和设置利益干系人的期望非常有用

试运行不需要太多的时间协调。 GitHub Enterprise Importer 从不要求正在迁移的存储库用户停机。 但是，建议在生产迁移期间停止工作，确保在迁移期间不会创建新数据（这些数据随后会从已迁移的存储库中丢失）。 这不是试迁移的问题，因此可以随时进行试运行。 若要减少完成试迁移所需的时间，可以连续安排试运行的批处理。 然后，这些存储库的用户可以自行安排进行结果验证。

We recommend creating a test organization to use as a destination for your trial migrations. 可以将单个组织用于所有试运行，也可以为每个预期目标组织创建一个测试组织。 请考虑在组织名称的末尾添加 -sandbox，以阐明组织仅用于迁移验证，而不适用于生产。 完成后，可以删除测试组织。

  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. （可选）删除测试组织。

Completing follow-up tasks

每次迁移完成后，需要先完成一些附加任务，然后存储库才能开始工作。

Checking the migration status

首先，检查迁移是成功还是失败。

检查迁移状态的方式取决于你运行迁移的方式。

  • 如果迁移是使用 GitHub CLI 运行的，则默认情况下，该进程将会显示迁移在迁移完成后是成功还是失败。 如果迁移失败，你将看到导致失败的原因。

    Migration completed (ID: RM_123)! State: SUCCEEDED

  • 如果迁移是使用 GitHub CLI 以及可选的 --queue-only 参数运行的，则该进程会在将该迁移加入队列后立即退出，并且不会告诉你迁移是成功还是失败。 可以使用 wait-for-migration 命令或通过查看迁移日志来检查迁移状态。

  • 如果迁移是使用 GraphQL API 运行的，则可以查询 RepositoryMigration 对象上的 state 和 failureReason 字段。

如果迁移失败，迁移日志可能包含有关失败原因的附加信息。 有关详细信息，请参阅查看迁移日志。

Reviewing the migration log

查看每个已迁移存储库的迁移日志。 有关详细信息，请参阅“访问 GitHub Enterprise Importer 的迁移日志”。

如果迁移失败，日志可能包含有关失败原因的附加信息。

如果迁移成功，则迁移日志中可能存在警告，说明未能迁移或虽然迁移但有注意事项的特定数据（例如，拉取请求、问题或注释）。

有关了解迁移警告的详细信息，请参阅“使用 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 添加组织成员到团队.

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 组织的存储库角色.

  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 提交除外）都归属于称为模型的占位符标识。

可以使用 GitHub CLI 或在浏览器中将每个模型的历史记录重新归因给组织成员。 如果使用 GitHub CLI，则可以批量回收模型。 有关详细信息，请参阅“回收 GitHub Enterprise Importer 的模型”。

注意

只有组织所有者才能回收模型。 如果已获得迁移者角色，请联系组织所有者执行此步骤。

  1. 决定是否要回收模型。
  2. 计划何时完成回收。
  3. 回收模型。
  4. 如果任何成员尚未通过团队成员身份具有存储库的适当访问权限，请授予该成员对存储库的访问权限。 有关详细信息，请参阅“管理个人对组织仓库的访问”。

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. 如果为目标企业禁用了标识提供者的 IP 允许列表限制，现在可以重新启用它们。

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