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 支持。如果你需要此工具的帮助，请在其存储库中打开一个问题。

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

迁移时间主要取决于存储库中的请求拉取和问题数量。如果你想迁移 1,000 个存储库，并且每个存储库平均有 100 个请求拉取和问题，而只有 50 个用户对这些存储库做出了贡献，那么你的迁移很可能会非常快。如果你只想迁移 100 个存储库，但这些存储库平均每个有 75,000 个请求拉取和问题，并且有 5,000 个用户，那么迁移将需要更长的时间，并且需要更多的规划和测试。

使用分析器后，你可以根据你想要的时间表权衡你的库存数据。如果你的组织可以承受较高的变更程度，那么你可能能够一次迁移所有存储库，在几天内完成迁移工作。但是，你可能有多个团队无法同时迁移。在这种情况下，你可能希望批量分批迁移，以适应团队的时间表，延长迁移工作。

为 GitHub CLI 使用 gh-repo-stats 扩展，然后查看你的迁移清单。
要了解团队何时可以准备好迁移，请采访利益相关者。
完全查看本指南的其余部分，然后确定迁移时间表。

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

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

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

查看为你的迁移源迁移的数据。更多信息，请参阅“关于 GitHub 产品之间的迁移”。
列出您需要手动迁移或重新创建的任何数据。

谁将运行迁移？

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

决定谁将运行组织迁移

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

此外，您还必须是目标企业帐户的企业所有者。您无法授予企业帐户的迁移者角色。

确认将运行您的迁移的人员是目标企业帐户的企业所有者。
如果该人员不是源组织的组织所有者，请授予他们该组织的迁移者角色。有关更多信息，请参阅“管理 GitHub 产品之间的迁移访问权限”。
确认该人员已正确配置个人访问令牌以满足所有访问要求。有关更多信息，请参阅“管理 GitHub 产品之间的迁移访问权限”。

决定谁将运行存储库迁移

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

决定您是否希望组织所有者执行您的迁移，或者您是否需要授予其他人迁移者角色。
如果您选择授予迁移角色，请决定将角色授予哪个人或团队。
将迁移角色授予该个人或团队。有关详细信息，请参阅“管理 GitHub 产品之间的迁移访问权限”。

注意：请记住，同时为源组织和目标组织授予迁移角色。
确认该人员已正确配置个人访问令牌以满足所有访问要求。有关更多信息，请参阅“管理 GitHub 产品之间的迁移访问权限”。

我们是否希望在迁移后保持类似的组织结构？

接下来，考虑您是否希望在迁移后保持类似的组织结构。如果您想将迁移工作分解为批次，这将帮助您确定批次。如果您打算在源组织和目标组织之间保持一对一对应关系，那么我们建议按组织对迁移进行批处理。这是最简单的方法，特别是如果您从 GitHub.com 迁移，因为您可以使用一个命令迁移整个组织。如果您从其他来源迁移，GitHub CLI 可以生成一个脚本，以迁移单个组织中的所有存储库。

如果您打算更改组织结构，请考虑其他批处理因素。您可以对由类似团队或业务部门拥有的存储库进行批处理，也可以按目标组织进行批处理。如果可能，我们建议按团队进行批处理。如果您按业务部门或目标组织进行批处理，您将增加涉及的利益相关者的数量，这可能会导致迁移时间窗口缩短。

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

注意：您可以同时运行多个批次。例如，如果您按团队进行批处理，则可以在同一时间窗口内运行多个团队的迁移。

决定您的新组织结构。
决定是否需要将迁移工作分解为较小的批次。
如果是，请决定如何分解迁移。

运行迁移

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

试运行迁移可帮助您确定几项关键信息。

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

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

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

如果您正在运行存储库迁移，请为您的试运行迁移创建一个测试组织。
如果您的源组织使用 IP 允许列表，请将该列表配置为允许 GitHub Enterprise Importer 访问。有关详细信息，请参阅“管理 GitHub 产品之间的迁移访问”。
运行试运行迁移。
为试运行迁移完成以下描述的后续任务。
要求用户验证迁移结果。
解决试运行迁移中发现的任何问题。
如果您的目标使用 IP 允许列表，请将该列表配置为允许 GitHub Enterprise Importer 访问。有关详细信息，请参阅“管理 GitHub 产品之间的迁移访问”。
如果您正在运行存储库迁移并且想要迁移 GitHub 高级安全设置，请为目标组织启用 GitHub 高级安全。有关详细信息，请参阅“管理组织的安全和分析设置”。
运行生产迁移。更多信息，请参阅“关于 GitHub Enterprise Importer”或“将组织从 GitHub.com 迁移到 GitHub Enterprise Cloud”。
选择性地删除测试组织。

完成后续任务

每个迁移完成后，在存储库可以开始工作之前，您需要完成一些其他任务。

检查迁移状态
查看迁移日志
迁移 Git LFS 对象
设置存储库可见性
配置 GitHub Actions
配置 IP 允许列表
管理 GitHub 高级安全性
启用 Webhook
重新安装 GitHub 应用
重新创建团队
回收傀儡

检查迁移状态

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

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

如果您使用 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 对象推送到迁移后的代码仓库。有关更多信息，请参阅“复制代码仓库”。

设置代码仓库可见性

所有代码仓库都作为私有代码仓库迁移，只有运行迁移的用户和组织所有者才能访问该代码仓库。如果你不希望代码仓库为私有，请更改可见性。

你可以在浏览器中更改代码仓库的可见性。有关更多信息，请参阅“设置代码仓库可见性”。
或者，你可以使用 GitHub CLI 从命令行更改代码仓库可见性。你甚至可以将此命令添加到用于运行迁移的脚本中。有关更多信息，请参阅 GitHub CLI 文档中的 gh repo edit。

配置 GitHub Actions

如果你在代码仓库中使用 GitHub Actions，你的工作流将作为 Git 代码仓库的一部分自动迁移。

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

如果你使用较大的运行程序、自托管运行程序或加密密钥，则必须重新配置它们。

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

如果你使用自托管运行程序，请重新配置你的运行程序。
- 将运行程序添加到适当的代码库、组织或企业。有关详细信息，请参阅“添加自托管运行程序”。
- 要在组织或企业级别使用运行程序，请更新工作流。有关详细信息，请参阅“在工作流中使用自托管运行程序”。
如果您使用较大的运行程序，请重新配置您的运行程序。
- 配置运行程序组以控制对运行程序的访问。有关详细信息，请参阅“控制对较大的运行程序的访问”。
- 设置较大的运行程序。有关详细信息，请参阅“管理较大的运行程序”。
- 更新工作流以指向您的运行程序。有关详细信息，请参阅“在较大的运行程序上运行作业”。
重新添加任何加密密钥。
- 要使用浏览器，请参阅“在 GitHub Actions 中使用密钥”。
- 要使用 GitHub CLI，请参阅 GitHub CLI 文档中的 gh secret。
重新配置环境。有关详细信息，请参阅“使用环境进行部署”。