在 GitHub 产品之间迁移的概述

了解如何完成使用 GitHub Enterprise Importer 从一个 GitHub 产品迁移到另一个产品（从规划到实施再到完成后续任务）的整个过程。

本文内容

概述

使用 GitHub Enterprise Importer 可以迁移到 GitHub Enterprise Cloud。 有关详细信息，请参阅“关于 GitHub Enterprise Importer”。

如果在 GitHub 产品之间迁移，例如从 GitHub Enterprise Server 迁移到 GitHub Enterprise Cloud，则可以使用本指南来规划和实现迁移并完成后续任务。 有关支持的迁移路径的完整列表，请参阅“关于 GitHub Enterprise Importer”。

规划迁移

若要规划迁移，请自行思考以下问题。

按组织还是按存储库进行迁移？

首先，如果迁移源和目标都是 GitHub.com，请决定是要逐个组织迁移还是逐个存储库迁移。

注意： 如果从 GitHub Enterprise Server 迁移，则只能迁移存储库。

如果选择逐个存储库迁移，则仅迁移存储库级别的数据。 如果选择逐个组织迁移策略，则还会迁移选定的组织级别数据，包括团队及其对存储库的访问。

迁移组织时，会同时迁移源组织拥有的所有存储库。 你无法将存储库分成多个批次或不迁移组织的任何存储库。 如果你有大量存储库，或者如果你不能容忍所有存储库同时发生故障，你可能需要改为运行存储库迁移。

此外，组织迁移会在目标企业帐户中创建新的组织。 如果要将存储库迁移到现有组织中，则需要改为运行存储库迁移。

最后，你必须是目标企业帐户的企业所有者才能迁移组织。 如果要求非企业所有者执行迁移，则他们将需要运行存储库迁移。

需要多久才能完成迁移？

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

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

  • 存储库数目
  • 拉取请求数
  • 问题数
  • 用户数
  • 项目和 wikis 的使用情况

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

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

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

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

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

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

  1. 查看为迁移源迁移的数据。 有关详细信息，请参阅“关于 GitHub 产品之间的迁移”。
  2. 列出需要手动迁移或重新创建的所有数据。

谁将运行迁移？

决定谁将运行迁移，并确保其具有所需的访问权限。 你的选择取决于是按组织还是按存储库迁移。

决定谁将运行组织迁移

若要迁移组织，你必须是源组织的组织所有者，或者组织所有者必须授予你该组织的迁移者角色。

此外，你必须是目标企业帐户的企业所有者。 不能为企业帐户授予迁移者角色。

  1. 确认将运行迁移的用户是否是目标企业帐户的企业所有者。
  2. 如果该用户不是源组织的组织所有者，请授予其组织的迁移者角色。 有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。
  3. 确认此人已正确配置 personal access token 以满足所有访问要求。 有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。

决定谁将运行存储库迁移

若要迁移仓库，你必须是源组织和目标组织的组织所有者，如果你不是组织所有者，组织所有者必须授予你各组织的迁移者角色。

  1. 决定是要组织所有者执行迁移，还是要将迁移者角色授予其他用户。

  2. 如果选择授予迁移者角色，请决定将向哪个人或团队授予该角色。

  3. 向个人或团队授予迁移者角色。 有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。

    注意： 请记住为源组织和目标组织授予迁移者角色。

  4. 确认此人已正确配置 personal access token 以满足所有访问要求。 有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。

是否要在迁移后保持类似的组织结构？

接下来，考虑是否要在迁移后保持类似的组织结构。 如果要将迁移工作分成多个批次，这将有助于你确定批次。 如果要在源和目标中的组织之间保持一对一的对应关系，建议按组织进行分批迁移。 这是最简单的方法，尤其是要从 GitHub.com 迁移时，因为可以使用一个命令迁移整个组织。 如果从另一个源迁移，GitHub CLI 可以生成一个脚本来迁移单个组织中的所有存储库。

如果要更改组织结构，请考虑其他分批因素。 你可以将类似团队或业务部门拥有的存储库分到同一批，也可以按目标组织分批。 如果可能，建议按团队分批。 如果按业务部门或目标组织分批，涉及的利益干系人将增多，可能会导致迁移时段变短。

即使更改了组织结构，你仍可以为迁移准备脚本。 使用 GitHub CLI 命令，然后根据需要将每个存储库的行移动到不同的脚本中。

注意： 你可以同时运行多个批。 例如，如果按团队分批，则可以在同一时段为多个团队运行迁移。

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

运行迁移

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

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

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

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

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

  1. 如果正在运行存储库迁移，请为试验迁移创建测试组织。
  2. 如果源组织使用 IP 允许列表，请将列表配置为允许 GitHub Enterprise Importer 进行访问。 有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。
  3. 运行试验性迁移。
  4. 完成下面所述的试验性迁移后续任务。
  5. 要求用户验证迁移结果。
  6. 解决试验性迁移发现的任何问题。
  7. 如果目标使用 IP 允许列表，请将列表配置为允许 GitHub Enterprise Importer 进行访问。 For more information，请参阅“管理 GitHub 产品之间迁移的访问权限”。
  8. 如果正在运行存储库迁移并且想要迁移 GitHub Advanced Security 设置，请为目标组织启用 GitHub Advanced Security。 有关详细信息，请参阅“管理组织的安全和分析设置”。
  9. 运行生产迁移。 有关详细信息，请参阅“关于 GitHub Enterprise Importer”或“将组织从 GitHub.com 迁移到 GitHub Enterprise Cloud”。
  10. （可选）删除测试组织。

完成后续任务

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

检查迁移状态

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

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

  • 如果迁移是使用 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 排查迁移问题”。 查看任何迁移警告后，需要决定是否可以接受这些警告并继续下一步操作。

迁移 Git LFS 对象

GitHub Enterprise Importer 不迁移 Git LFS 对象。 如果源存储库使用 Git LFS，你可以在本地手动将 Git LFS 对象推送到迁移后的存储库。 有关详细信息，请参阅“复制仓库”。

设置存储库可见性

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

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

配置 GitHub Actions

如果在存储库中使用 GitHub Actions，则工作流将作为 Git 存储库的一部分自动迁移。

在迁移过程中，为所有迁移后的存储库禁用 GitHub Actions，以避免意外触发工作流，但迁移完成后，请重新启用 GitHub Actions。

如果使用的是 大型运行器 自托管运行器或加密机密，则必须对其进行重新配置。

注意： 迁移中不包含 GitHub Actions 的工作流运行历史记录。

  1. 如果使用自托管运行器，请重新配置运行器。

  2. 如果使用 大型运行器，请重新配置运行器。

  3. 重新添加任何加密机密。

  4. 重新配置环境。 有关详细信息，请参阅“管理部署环境”。

配置 IP 允许列表

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

有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。

管理 GitHub Advanced Security

如果在迁移存储库之前为目标组织启用了 GitHub Advanced Security，则已迁移各个功能的设置。 如果未启用，则需在迁移后重新启用各个功能。 有关详细信息，请参阅“管理存储库的安全和分析设置”。

每个功能都有额外的迁移后步骤。

Secret scanning

为目标存储库启用机密扫描后，将执行对整个存储库的扫描。 扫描完成后，将填充所有警报，但不含修正状态。

你可以使用 REST API 更新警报，以反映源存储库中的所有修正措施。 有关详细信息，请参阅“适用于机密扫描的 REST API 终结点”。

与这些更新的修正关联的用户将是拥有用于 API 调用的 personal access token 的用户，而不是在源存储库中修正警报的用户，并且与修正相关的日期将是 API 调用的日期，而不是在源存储库中修正警报时的日期。

Code scanning

Code scanning 警报不由 GitHub Enterprise Importer 进行迁移。 但警报在源存储库中可作为 SARIF 数据提供。 你可以使用 REST API 将此数据上传到目标存储库。 有关详细信息，请参阅“适用于代码扫描的 REST API 终结点”。

以这种方式填充的 Code scanning 警报将不同于源存储库中的初始警报。

  • 警报将仅包括警报的检测和最新状态，不包括来自源存储库的整个时间线。
  • 警报将仅被标识为 open 或 fixed。 dismissed 和 reopened 等其他修正状态将丢失。
  • 警报中所有事件的日期将是 API 调用的日期，而不是事件最初在源存储库中发生时的日期。
  • 所有参与者（例如警报创建者）将变更为 API 调用所用的 personal access token 的所有者。

Dependabot alerts

启用 Dependabot alerts 和依赖项关系图时，将根据默认分支的当前状态重新生成 Dependabot alerts。 不会迁移这些警报的修正状态，也不会迁移任何以前的警报。

你需要为 Dependabot 重新添加所有加密机密。 有关详细信息，请参阅“为 Dependabot 配置对专用注册表的访问权限”。

启用 webhook

迁移源存储库中的所有活动 webhook。 但是，默认情况下将禁用迁移后的 webhook。 你可以在存储库设置中重新启用这些 webhook。

  1. 导航到迁移后的存储库的设置。
  2. 在边栏的“代码和自动化”部分，单击“Webhook”。
  3. 在要启用的 Webhook 右侧，单击“编辑”。
  4. 如果使用机密令牌来保护 webhook，请在“机密”下重新添加机密。
  5. 在页面底部，选择“活动”。
  6. 单击“更新 Webhook”。

重新安装 GitHub Apps

如果你在源存储库上安装了任何 GitHub Apps，则需要在迁移后的存储库上对其进行重新安装。 有关详细信息，请参阅“安装自己的 GitHub 应用”。

重新创建团队

如果是逐个组织迁移的，则只需恢复团队成员身份。 如果逐个存储库迁移，则需要重新创建团队，授予这些团队对存储库的访问权限，然后恢复团队成员身份。

为组织迁移重新创建团队

组织迁移期间会迁移团队及其存储库访问权限，但不迁移团队成员身份。 迁移后，必须将用户添加到迁移后的团队。

强烈建议使用团队同步通过标识提供者 (IdP) 管理团队成员身份。 有关详细信息，请参阅“为企业托管用户配置 SCIM 预配”，对于不使用 Enterprise Managed Users 的企业，请参阅“管理企业中组织的团队同步”。

在其他情况下，你可以手动将成员添加到组织，然后将组织成员添加到团队。 有关详细信息，请参阅“添加组织成员到团队”。

为存储库迁移重新创建团队

存储库迁移期间不会迁移团队。 你必须手动重新创建团队并授予每个团队对存储库的访问权限。

  1. 重新创建团队。 有关详细信息，请参阅“创建团队”。
  2. 在团队中添加组织成员。 有关详细信息，请参阅“添加组织成员到团队”。
  3. 为每个团队授予对存储库的访问权限。 有关详细信息，请参阅“管理团队对组织仓库的访问”。

回收模型

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

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

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

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