从 Azure DevOps 迁移到 GitHub 企业云的概述

了解如何使用 GitHub 企业导入器完成从 Azure DevOps 迁移到 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，并假设您使用的是 GitHub CLI 的 ADO2GH 扩展。

规划您的迁移

要规划您的迁移，请自问以下问题。

我们什么时候需要完成迁移？

确定您的时间线，这将在很大程度上决定您的方法。确定时间线的第一个步骤是获取您需要迁移的内容的清单。要收集此数据，请使用 GitHub CLI 的 gh-repo-stats 扩展。此开源工具会生成一份报告，详细说明组织需要迁移多少数据。

注意：gh-repo-stats 是一个第三方开源工具，不受 GitHub 支持。如果您需要有关此工具的帮助，请在 其存储库中打开问题。

  • 仓库数量
  • 拉取请求数量

迁移时间主要取决于仓库中 Pull Request 的数量。如果您要迁移 1000 个仓库，每个仓库平均有 100 个 Pull Request，并且只有 50 个用户贡献过这些仓库，那么您的迁移速度可能会很快。如果您只想迁移 100 个仓库，但每个仓库平均有 75,000 个 Pull Request，并且有 5,000 个用户，那么迁移将花费更长时间，需要更多计划和测试。

使用分析器后，您可以将您的库存数据与您期望的时间线进行比较。如果您的组织能够承受更高程度的变化，那么您可能能够一次迁移所有仓库，并在几天内完成迁移工作。但是，您可能会有不同的团队无法同时迁移。在这种情况下，您可能需要将迁移进行批次处理并错开时间，以适应团队的时间线，从而延长迁移工作。

  1. 使用 gh-repo-stats 扩展 用于 GitHub CLI，然后查看您的迁移库存。
  2. 为了了解团队何时可以准备好迁移，请与利益相关者进行访谈。
  3. 完整查看本指南的其余部分，然后确定迁移时间线。

注意：gh-repo-stats 是一个第三方开源工具，不受 GitHub 支持。如果您需要有关此工具的帮助，请在 其存储库中打开问题。

我们是否了解要迁移的内容？

确保您和您的利益相关者了解 GitHub Enterprise Importer 可以迁移哪些数据。

对于从 ADO 迁移，GitHub Enterprise Importer 仅迁移 Git 仓库，包括 Pull Request 和一些分支策略。任何其他资产，例如管道、工作项、工件、测试计划、发布和仪表板，将保留在 ADO 中。

由于 GitHub 中的权限与 ADO 中的权限不同，因此 GitHub Enterprise Importer 不会尝试从 ADO 迁移仓库权限。有关更多信息，请参阅“配置权限”。

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

  1. 查看从 Azure DevOps 迁移的数据。有关更多信息，请参阅“关于从 Azure DevOps 迁移到 GitHub Enterprise Cloud”。
  2. 列出您需要手动迁移或重新创建的任何数据。

谁将运行迁移？

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

  1. 确定您是否希望目标组织的组织所有者执行您的迁移，或者您是否需要将迁移者角色授予其他人。
  2. 如果您选择授予迁移者角色，请确定您将授予该角色的个人或团队。
  3. 将迁移者角色授予个人或团队。有关更多信息，请参阅“管理来自 Azure DevOps 的迁移的访问权限”。
  4. 确认该人员已正确配置个人访问令牌以满足所有访问要求。有关更多信息，请参阅“管理来自 Azure DevOps 的迁移的访问权限”。

我们希望在 GitHub 中使用什么组织结构？

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

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

注意：团队项目的概念用于在 ADO 中对存储库进行分组，在 GitHub 中不存在。我们不建议将 GitHub 中的组织视为 ADO 中团队项目的等效项。

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

这可能会导致每个组织中出现大量未分组的存储库列表。但是，您可以通过创建团队来管理对存储库组的访问权限。有关更多信息，请参阅“关于团队”。

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

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

运行迁移

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

试运行迁移有助于您确定一些关键信息。

  • 给定存储库的迁移是否可以成功完成
  • 您是否可以将存储库恢复到用户可以成功开始工作的状态
  • 迁移运行需要多长时间，这对于规划迁移时间表和设定利益相关者预期很有用

试运行不需要太多时间协调。GitHub Enterprise Importer 永远不会要求正在迁移的存储库的用户停机。但是，我们建议在生产迁移期间停止工作，以确保在迁移期间不会创建新数据，否则这些数据将从迁移的存储库中丢失。这对于试运行迁移来说不是问题，因此试运行可以在任何时间进行。为了减少完成试运行迁移所需的时间，您可以将试运行的批次安排得背靠背。然后，这些存储库的用户可以在自己的时间内验证结果。

我们建议创建一个测试组织，用作试运行迁移的目标。您可以对所有试运行使用单个组织，也可以为每个目标组织创建一个测试组织。考虑在组织名称的末尾包含 -sandbox，以明确说明这些组织仅用于迁移验证，而不是用于生产。完成迁移后，您可以删除测试组织。

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

完成后续任务

每次迁移完成后，您需要完成一些额外的任务，才能使仓库准备好工作。

检查迁移状态

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

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

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

    Migration completed (ID: RM_123)! State: SUCCEEDED

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

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

如果迁移失败，迁移日志可能包含有关失败原因的更多信息。有关更多信息，请参阅“查看迁移日志”。

查看迁移日志

查看每个迁移仓库的迁移日志。有关更多信息，请参阅“访问 GitHub Enterprise Importer 的迁移日志”。

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

如果迁移成功，迁移日志中可能会出现警告，表示某些特定数据（例如拉取请求、问题或评论）未迁移或迁移时存在问题。

有关了解迁移警告的更多信息，请参阅“使用 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 允许列表限制，则现在可以重新启用它们。

有关更多信息，请参阅“管理从 Azure DevOps 迁移的访问权限”。