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

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

迁移时间主要取决于存储库中拉取请求和问题的数量。如果您要迁移 1000 个存储库，并且每个存储库平均有 100 个拉取请求和问题，只有 50 个用户为这些存储库做出了贡献，那么您的迁移可能会非常快。如果您只想迁移 100 个存储库，但每个存储库平均有 75,000 个拉取请求和问题，以及 5000 个用户，则迁移将花费更长时间，并且需要更多计划和测试。

使用分析器后，您可以根据所需的时限权衡您的库存数据。如果您的组织能够承受更高程度的变化，那么您也许能够一次迁移所有存储库，并在几天内完成迁移工作。但是，您可能有多个无法同时迁移的团队。在这种情况下，您可能希望将迁移分批进行并交错执行，以适应团队的时间安排，从而延长迁移工作。

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

注意

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

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

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

  1. 查看迁移源中迁移的数据。有关更多信息，请参阅“GitHub 产品之间的迁移简介”。
  2. 列出您需要手动迁移或重新创建的任何数据。

谁将运行迁移？

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

确定谁将运行组织迁移

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

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

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

确定谁将运行存储库迁移

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

  1. 确定您是否希望组织所有者执行您的迁移，或者您是否需要向其他人授予迁移者角色。

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

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

    注意

    请记住，要为源组织和目标组织都授予迁移者角色。

  4. 确认该人员已正确配置个人访问令牌以满足所有访问要求。有关更多信息，请参阅“管理 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 访问。有关更多信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。
  8. 如果您正在运行存储库迁移并希望迁移 GitHub 高级安全设置，请为目标组织启用 GitHub 高级安全。有关更多信息，请参阅“管理组织的安全和分析设置”。
  9. 运行生产迁移。有关更多信息，请参阅“关于 GitHub Enterprise Importer”或“将组织从 GitHub.com 迁移到 GitHub Enterprise Cloud”。
  10. 可选：删除测试组织。

完成后续任务

每次迁移完成后，您都需要完成一些其他任务，然后存储库才能准备好工作。

检查迁移状态

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

检查迁移状态的方法取决于您如何运行迁移。

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

    Migration completed (ID: RM_123)! State: SUCCEEDED

  • 如果您使用带有可选 --queue-only 参数的 GitHub CLI 运行迁移，则该过程将在排队迁移后立即退出，并且不会告诉您迁移成功或失败。您可以使用 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 高级安全

如果您在迁移存储库之前为目标组织启用了 GitHub 高级安全，则各个功能的设置将被迁移。如果没有，您需要在迁移后重新启用各个功能。有关更多信息，请参阅“管理存储库的安全和分析设置”。

每个功能都有其他迁移后步骤。

密钥扫描

当为目标存储库启用密钥扫描时，将执行整个存储库的扫描。扫描完成后，将填充所有警报，但不会显示修复状态。

您可以使用 REST API 更新警报以反映源存储库中的任何修复。有关更多信息，请参阅“密钥扫描的 REST API 端点”。

与这些更新的修复关联的用户将是拥有用于 API 调用的个人访问令牌的用户，而不是在源存储库中修复警报的用户，并且与修复关联的日期将是 API 调用的日期，而不是警报在源存储库中修复的日期。

代码扫描

代码扫描警报不会由 GitHub Enterprise Importer 迁移。但是，这些警报作为 SARIF 数据存在于源存储库中。您可以使用 REST API 将此数据上传到目标存储库。有关更多信息，请参阅“代码扫描的 REST API 端点”。

以这种方式填充的代码扫描警报将与源存储库中的原始警报有所不同。

  • 警报将仅包含检测和警报的最新状态，而不是源存储库中的整个时间线。
  • 警报将仅标识为 open 或 fixed。其他修复状态（如 dismissed 和 reopened）将丢失。
  • 警报上所有事件的日期将是 API 调用的日期，而不是事件最初在源存储库中发生的日期。
  • 所有参与者（例如警报创建者）都将更改为用于 API 调用的个人访问令牌的所有者。

Dependabot 警报

启用 Dependabot 警报和依赖关系图后，Dependabot 警报将根据默认分支的当前状态重建。这些警报的修复状态不会迁移，并且任何以前的警报也不会迁移。

您需要为 Dependabot 重新添加任何加密的密钥。有关更多信息，请参阅“为 Dependabot 配置对私有注册表的访问权限”。

重新配置数据驻留功能

如果您已从 GitHub.com 迁移到具有数据驻留功能的 GitHub Enterprise Cloud，则某些功能的工作方式有所不同，并且某些功能将需要不同的或其他配置。请参阅“具有数据驻留功能的 GitHub Enterprise Cloud 的功能概述”。

启用 Webhook

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

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

重新安装 GitHub Apps

如果您在源存储库中安装了任何 GitHub Apps，则需要在迁移的存储库中重新安装它们。有关更多信息，请参阅“安装您自己的 GitHub App”。

重新创建团队

如果您按组织为单位进行迁移，则只需恢复团队成员资格即可。如果您按存储库为单位进行迁移，则需要重新创建团队，授予这些团队对存储库的访问权限，然后恢复团队成员资格。

为组织迁移重新创建团队

团队及其存储库访问权限作为组织迁移的一部分进行迁移，但团队成员资格不会迁移。迁移后，您必须将用户添加到迁移的团队中。

我们强烈建议使用团队同步来通过您的身份提供商 (IdP) 管理团队成员身份。有关更多信息，请参阅“配置 SCIM 配置文件以管理用户”或，对于不使用企业托管用户的企业，“管理企业中组织的团队同步”。

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

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

团队不会作为存储库迁移的一部分进行迁移。您必须手动重新创建团队并为每个团队授予对存储库的访问权限。

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

回收虚拟用户

在使用 GitHub Enterprise Importer 运行迁移后，迁移的存储库中所有用户活动（Git 提交除外）都将归因于称为虚拟用户的占位符身份。

您可以使用 GitHub CLI 或在浏览器中将每个虚拟用户的历史记录重新分配给组织成员。如果使用 GitHub CLI，则可以批量回收虚拟用户。有关更多信息，请参阅“回收 GitHub Enterprise Importer 的虚拟用户”。

注意

只有组织所有者才能回收虚拟用户。如果您已获得迁移者角色，请联系组织所有者以执行此步骤。

  1. 确定是否要回收虚拟用户。
  2. 计划何时完成回收。
  3. 回收虚拟用户。
  4. 如果任何成员尚未通过团队成员身份获得对存储库的适当访问权限，请为成员授予对存储库的访问权限。有关更多信息，请参阅“管理个人对组织存储库的访问权限”。