GitHub 产品之间迁移概览 - 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 迁移，只能迁移仓库。

如果您选择按仓库逐个迁移，仅会迁移仓库级别的数据。如果您选择按组织逐个迁移，还会迁移所选组织级别的数据，包括团队及其对仓库的访问权限。

然而，当您迁移一个组织时，源组织拥有的所有仓库都会一次性迁移。您不能将仓库拆分成批次，也不能跳过迁移组织的任何仓库。如果仓库数量众多，或者您无法容忍所有仓库同时停机，可能需要改为执行仓库迁移。

此外，组织迁移会在目标企业帐户中创建一个新组织。如果您想将仓库迁移到已存在的组织，则必须改为执行仓库迁移。

最后，迁移组织时您必须是目标企业帐户的企业所有者。如果您希望指派非企业所有者执行迁移，他们只能进行仓库迁移。

我们需要在多快的时间内完成迁移？

确定时间表，这将主要决定您的迁移方式。确定时间表的第一步是获取需要迁移的清单。要收集此数据，请使用 gh-repo-stats 扩展（GitHub CLI 插件）。此开源工具会生成一份报告，详细说明组织需要迁移的数据量。

注意

gh-repo-stats 是第三方开源工具，GitHub 支持不对其提供支持。如果您在使用此工具时需要帮助，请在其仓库中打开 issue。

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

迁移时长主要取决于仓库中的拉取请求和问题数量。如果您要迁移 1,000 个仓库，而每个仓库平均有 100 条拉取请求和问题，并且只有 50 位用户参与贡献，迁移可能会非常快速。相反，如果您只迁移 100 个仓库，但每个仓库平均有 75,000 条拉取请求和问题，且涉及 5,000 位用户，则迁移会耗时更长，需要更多的规划和测试。

使用分析器后，您可以将清单数据与期望的时间表进行对比。如果您的组织能够承受更高程度的变更，可能一次性迁移所有仓库，仅需几天即可完成迁移工作。但如果有多个团队无法同时迁移，则可能需要分批、错峰进行迁移，以匹配各团队的时间表，从而延长整体迁移周期。

使用 gh-repo-stats 扩展（GitHub CLI），然后审查您的迁移清单。
要了解团队何时可以准备迁移，请访谈相关方。
完整阅读本指南其余部分，然后决定迁移时间表。

注意

gh-repo-stats 是第三方开源工具，GitHub 支持不对其提供支持。如果您在使用此工具时需要帮助，请在其仓库中打开 issue。

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

确保您和相关方了解 GitHub Enterprise Importer 能迁移哪些数据。

审查迁移源可迁移的数据。有关更多信息，请参阅关于在 GitHub 产品之间的迁移。
列出需要手动迁移或重新创建的任何数据。

谁将执行迁移？

决定谁将执行迁移，并确保此人拥有所需的访问权限。您的选择取决于是按组织还是按仓库进行迁移。

决定谁将执行组织迁移

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

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

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

决定谁将执行仓库迁移

要迁移仓库，您必须是源组织和目标组织的组织所有者，或由组织所有者在您不是所有者的组织上授予您迁移者角色。

决定是让组织所有者执行迁移，还是将迁移者角色授予其他人。
如果您选择授予迁移者角色，请决定将角色授予哪位人员或团队。
将迁移者角色授予该人员或团队。更多信息，请参阅管理 GitHub 产品之间迁移的访问权限。

注意

请记得在源组织和目标组织上都授予迁移者角色。
确认该人员已正确配置个人访问令牌以满足所有访问要求。更多信息，请参阅管理 GitHub 产品之间迁移的访问权限。

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

接下来，考虑迁移后是否希望保持相似的组织结构。如果您打算将迁移工作拆分为批次，这将帮助您确定批次方式。如果您打算在源和目标之间保持一对一对应的组织关系，建议按组织批量迁移。这是最简便的方式，尤其是在从 GitHub.com 迁移时，因为您可以使用一条命令迁移整个组织。如果您从其他来源迁移，GitHub CLI 可以生成脚本，一次性迁移单个组织中的所有仓库。

如果您计划更改组织结构，请考虑其他批次因素。您可以按相似团队或业务部门拥有的仓库进行批次，或按目标组织进行批次。我们建议尽可能按团队批次。如果按业务部门或目标组织批次，将涉及更多相关方，可能导致迁移窗口更短。

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

注意

您可以同时运行多个批次。例如，按团队批次时，可以在同一时间窗口内为多个团队执行迁移。

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

我们对企业和组织名称的计划是什么？

如果在 GitHub.com 上的账户之间迁移，请注意用户、组织和企业帐户的命名约束。如果需要在迁移中重新使用组织或企业名称，建议先改名而不是删除。改名后，名称会立即可供重新使用。

GitHub Enterprise 上的组织帐户共享同一命名空间；两个用户/组织帐户不能使用相同名称。GitHub Enterprise 上的企业帐户也共享同一命名空间；两个企业帐户不能使用相同名称。

执行迁移

为帮助发现可能特有于您企业的问题，我们强烈建议先进行一次试运行迁移。通过试运行，您将了解

特定仓库的迁移是否能够成功完成。
是否能够使迁移后的仓库恢复到可使用的状态。
迁移需要多长时间。

试运行可以随时进行，迁移期间无需暂停工作。为缩短完成试运行的时间，您可以将批次安排为连续执行。相应仓库的用户可以在自己的时间验证结果。

对于仓库迁移，我们建议创建一个测试组织作为试验迁移的目标。您可以为所有试验运行使用同一个组织，或为每个预期的目标组织创建一个测试组织。建议在组织名称末尾加上 -sandbox，以表明这些组织仅用于迁移验证而非生产。完成后可删除这些测试组织。

如果您正在执行仓库迁移，请为试验迁移创建一个测试组织。
如果源组织使用 IP 允许列表，请配置该列表以允许 GitHub Enterprise Importer 访问。更多信息，请参阅管理 GitHub 产品之间迁移的访问权限。
执行试运行迁移。
为试验迁移完成下面描述的后续任务。
请用户验证迁移结果。
解决试运行中发现的所有问题。
如果您的目标使用 IP 允许列表，请配置该列表以允许 GitHub Enterprise Importer 访问。更多信息，请参阅管理 GitHub 产品之间迁移的访问权限。
如果您正在执行仓库迁移并且想迁移 GitHub Advanced Security 产品的设置，请为目标组织启用 GitHub Advanced Security 产品。更多信息，请参阅管理组织的安全和分析设置。
运行生产迁移。更多信息，请参阅关于 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 CLI，请参阅 GitHub CLI 文档中的 gh secret。
重新配置环境。更多信息，请参阅管理部署环境。

配置 IP 访问白名单

如果您已在源或目标组织的 IP 允许列表中添加了 GitHub Enterprise Importer 的 IP 范围，现在可以将这些条目移除。如果您为目标企业禁用了身份提供商的 IP 允许列表限制，现在可以重新启用。

更多信息，请参阅管理 GitHub 产品之间迁移的访问权限。

管理 GitHub 高级安全功能

如果您在迁移仓库前已为目标组织启用 GitHub Advanced Security 产品，单个功能的设置会自动迁移。若未启用，则需要在迁移后重新启用各功能。更多信息，请参阅管理仓库的安全和分析设置。

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

密钥扫描

当目标仓库启用密钥扫描时，会对整个仓库执行一次扫描。扫描完成后，所有警报都会被填充，但不包含修复状态。

您可以使用 REST API 更新警报，以匹配源仓库中已进行的修复。更多信息，请参阅密钥扫描的 REST API 端点。

这些更新的修复所对应的用户将是用于 API 调用的个人访问令牌持有者，而非在源仓库中执行修复的用户；修复日期也会是 API 调用的日期，而非源仓库中实际修复的日期。

代码扫描

GitHub Enterprise Importer 不迁移代码扫描警报。不过，源仓库中的警报以 SARIF 数据形式存在。您可以使用 REST API 将此数据上传到目标仓库。更多信息，请参阅代码扫描的 REST API 端点。

通过这种方式填充的代码扫描警报会与源仓库中的原始警报不同。

警报仅包含检测信息及最新状态，而不包括源仓库的完整时间线。
警报仅标记为 open（打开）或 fixed（已修复）。其他修复状态，如 dismissed（已取消）和 reopened（已重新打开），将会丢失。
所有事件的日期都将是 API 调用的日期，而不是源仓库中实际发生的日期。
所有参与者（例如警报创建者）均会变更为用于 API 调用的个人访问令牌所有者。

转到已迁移仓库的设置页面。
在侧边栏的“代码和自动化”部分，单击 Webhook。
在您想要启用的 Webhook 右侧，单击编辑。
如果您之前使用密钥令牌来保护 Webhook，请在“Secret”栏重新添加密钥。
在页面底部，选择 Active（已启用）。
单击 更新 Webhook。

否则，您可以手动向组织添加成员，然后再将组织成员添加到团队。更多信息，请参阅向团队添加组织成员。

仓库迁移的团队重新创建

仓库迁移不会迁移团队。您必须手动重新创建团队并为每个团队分配仓库访问权限。

重新创建团队。更多信息，请参阅创建组织团队。
向团队添加组织成员。更多信息，请参阅向团队添加组织成员。
为每个团队分配仓库访问权限。更多信息，请参阅管理组织仓库的团队访问权限。

回收人偶

使用 GitHub Enterprise Importer 运行迁移后，已迁移仓库中的所有用户活动（Git 提交除外）都会归因于称为人偶的占位身份。

注意

只有组织所有者可以回收人偶。如果您被授予迁移者角色，请联系组织所有者执行此步骤。

决定是否要回收人偶。
规划何时完成回收工作。
回收人偶。您可以使用 GitHub CLI 或在浏览器中将每个人偶的历史重新归属给组织成员。如果使用 GitHub CLI，您可以批量回收人偶。了解更多，请参阅GitHub Enterprise Importer 的人偶回收。
如果其中任何成员尚未通过团队成员资格获得对仓库的适当访问权限，请为这些成员授予仓库访问权限。了解更多，请参阅管理个人对组织仓库的访问。

GitHub 产品之间迁移的概览

本文内容

概览