使用 GitHub Enterprise Importer 从 Azure DevOps 迁移

本文内容

了解如何完成从 Azure DevOps 迁移到 GitHub 的整个过程（从计划、实现到完成后续任务）。

关于从 Azure DevOps 迁移

使用 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 迁移分析器。 此开源工具会生成一个报表，其中详细说明了要为组织迁移的数据量。

  • 存储库数目
  • 拉取请求数

迁移时间主要基于存储库中的拉取请求数。 如果要迁移 1000 个存储库，每个存储库平均有 100 个拉取请求，并且只有 50 个用户为存储库做了贡献，则迁移可能非常快。 如果只需迁移 100 个存储库，但每个存储库平均有 75000 个拉取请求和 5000 个用户，则迁移需要更长的时间，并且需要更多的计划和测试。

使用分析器后，可以根据所需的时间线权衡清单数据。 如果组织能够承受更高程度的更改，则可以一次性迁移所有存储库，在几天内完成迁移工作。 但可能有多个团队无法同时进行迁移。 在这种情况下，你可能需要分批和错开迁移来适应团队的时间线，以便最大化完成迁移工作。

  1. 使用 GitHub Migration Analyzer，然后查看迁移清单。
  2. 若要了解团队何时可以准备好迁移，请询问利益干系人。
  3. 全面了解本指南的其余部分，然后确定迁移时间线。

是否了解将迁移哪些内容？

确保你和你的利益干系人了解 GitHub Enterprise Importer 可以迁移哪些数据。

对于从 ADO 迁移，GitHub Enterprise Importer 仅迁移 Git 存储库（包括拉取请求和某些分支策略）。 任何其他资产（例如如管道、工作项、项目、测试计划、发布和仪表板）都将保留在 ADO 中。

由于 GitHub 中权限的使用方式与在 ADO 中的不同，因此 GitHub Enterprise Importer 不会尝试从 ADO 迁移存储库权限。 有关详细信息，请参阅“配置权限”。

服务挂钩不会从 ADO 迁移，因此需要单独重新创建。

  1. 查看从 Azure DevOps 迁移的数据。 有关详细信息，请参阅“GitHub Enterprise Importer 的迁移支持”。
  2. 列出需要手动迁移或重新创建的所有数据。

谁将运行迁移？

若要迁移存储库，你必须是目标组织的组织所有者，或者组织所有者必须向你授予迁移者角色。

  1. 确定是否需要目标组织的组织所有者执行迁移，还是需要向其他人授予迁移者角色。
  2. 如果选择授予迁移者角色，请决定将向哪个人或团队授予该角色。
  3. 向个人或团队授予迁移者角色。 有关详细信息，请参阅“为 GitHub Enterprise Importer 授予迁移者角色”。
  4. 确认此人已正确配置 personal access token 以满足所有访问要求。 有关详细信息，请参阅“管理 GitHub Enterprise Importer 的访问权限”。

我们需要 GitHub 的什么组织结构？

接下来，计划将在 GitHub 中创建的组织结构。 ADO 和 GitHub 组织企业工作的方式不同。

  • ADO：组织>团队项目>存储库
  • GitHub：企业>组织>存储库

注意：在 ADO 中用来为存储库分组的团队项目概念在 GitHub 中不适用。 不建议将 GitHub 中的组织视为等同于 ADO 中的团队项目。

迁移到 GitHub 后，应只有一个企业帐户和该企业拥有的少量组织。 ADO 中的每个组织都应与 GitHub 上的单个组织相对应。 不建议在 GitHub 上为 ADO 中的每个团队项目创建一个组织。

这可能会导致每个组织内出现大量未分组的存储库。 但你可以创建团队来管理对存储库组的访问。 有关详细信息，请参阅“关于团队”。

如果要将迁移工作划分为多批进行，新结构可用于确定批处理。 如果 ADO 中有多个组织，并且每个组织的存储库都是合理大小的批次，请考虑按组织进行批处理。 可以使用 GitHub CLI 在 ADO 上为整个组织生成迁移脚本。

  1. 决定新组织结构。
  2. 决定是否需要将迁移工作分解成更小的批次。
  3. 如果需要，请决定要如何分解迁移。

运行迁移

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

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

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

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

建议创建一个测试组织，用作试验性迁移的目标。 可以将单个组织用于所有试运行，也可以为每个预期目标组织创建一个测试组织。 请考虑在组织名称的末尾添加 -sandbox，以阐明组织仅用于迁移验证，而不适用于生产。 完成后，可以删除测试组织。

  1. 为试验性迁移创建测试组织。
  2. 运行试验性迁移。 有关详细信息，请参阅“准备使用 GitHub Enterprise Importer 运行迁移”。
  3. 完成下面所述的试验性迁移后续任务。
  4. 要求用户验证迁移结果。
  5. 解决试验性迁移发现的任何问题。
  6. 如果目标使用 IP 允许列表，请将列表配置为允许 GitHub Enterprise Importer 进行访问。 有关详细信息，请参阅“管理 GitHub Enterprise Importer 的访问权限”。
  7. 运行生产迁移。 有关详细信息，请参阅“将存储库从 Azure DevOps 迁移到 GitHub Enterprise Cloud”。
  8. （可选）删除测试组织。

完成后续任务

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

查看迁移日志

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

如果存储库中的任何特定项无法迁移，你将在迁移日志中看到警告。

注意：如果“迁移日志”问题在底部包含“迁移已完成”，则表明已迁移存储库。 错误消息仅指示存储库中的特定项（例如对拉取请求的注释）可能未正确迁移。

  1. 查看迁移日志。
  2. 查看每个日志的任何警告，并确保没有任何警告会阻止接受迁移。 有关详细信息，请参阅“使用 GitHub Enterprise Importer 排查迁移问题”。

设置存储库可见性

所有存储库都作为专用存储库迁移，只有运行迁移的用户和组织所有者才有权访问存储库。 如果不希望存储库成为专用存储库，请更改可见性。

  • 可以在浏览器中更改存储库的可见性。 有关详细信息，请参阅“设置存储库可见性”。
  • 或者，可以使用 GitHub CLI 从命令行更改存储库可见性。 甚至可以将此命令添加到为运行迁移而生成的脚本。 有关详细信息，请参阅 GitHub CLI 文档中的“gh repo edit”。

配置权限

由于 GitHub 中权限的使用方式与在 ADO 中的不同，因此 GitHub Enterprise Importer 不会尝试从 ADO 迁移存储库权限。

如果使用 ADO2GH CLI，GitHub Enterprise Importer 将在 GitHub 中为 ADO 中的每个团队项目创建两个团队。 每个团队被授予面向所有源自团队项目的存储库的不同级别的访问权限。

组对已迁移的存储库的访问
TEAM-PROJECT-Maintainers维护者
TEAM-PROJECT-Admins管理员

若要授予面向迁移存储库的访问权限，可以将人员添加到这些团队。 可以在 GitHub 上手动执行此操作，也可以选择在迁移过程中将团队链接到 Azure Active Directory (AAD) 组，即可在 AAD 中管理组成员身份。 有关手动管理团队成员身份的详细信息，请参阅“添加组织成员到团队”。

如果未使用 ADO2GH CLI，或者需要比此默认值更高级的权限配置，请为迁移的存储库配置权限。 可以根据需要修改迁移脚本，也可以在迁移后手动配置权限。 有关管理对 GitHub 上存储库的访问的详细信息，请参阅“组织的存储库角色”。

  1. 确定 GitHub 中所需的权限结构。
  2. 如果不同于默认值，请制定计划来设置团队成员身份和权限。

回收模型

使用 GitHub Enterprise Importer 运行迁移后，已迁移的存储库中的所有用户活动（Git 提交除外）都归属于称为模型的占位符标识。

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

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

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

配置 IP 允许列表

如果将 GitHub Enterprise Importer 的 IP 范围添加到了目标组织的 IP 允许列表，则可以删除这些项。 如果为目标企业禁用了标识提供者的 IP 允许列表限制，现在可以重新启用它们。

有关详细信息，请参阅“管理 GitHub Enterprise Importer 的访问权限”。