从 Bitbucket Server 迁移到 GitHub Enterprise Cloud 的概述

了解使用 GitHub Enterprise Importer 从 Bitbucket Server 迁移到 GitHub 的过程（从计划、实现到完成后续任务）。

本文内容

概述

使用 GitHub Enterprise Importer，可以以存储库为单位逐个迁移到 GitHub Enterprise Cloud。 有关详细信息，请参阅“关于 GitHub Enterprise Importer”。

如果要从 Bitbucket Server 迁移，可以使用本指南来计划和实现迁移，并完成后续任务。

规划迁移

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

需要多久才能完成迁移？

确定时间线，这将在很大程度上决定你的方法。 若要确定时间线，第一步是获取需迁移内容的清单。

  • 存储库数目
  • 拉取请求数

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

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

  1. 确定需要迁移的存储库和拉取请求数。
  2. 若要了解团队何时可以准备好迁移，请询问利益干系人。
  3. 全面了解本指南的其余部分，然后确定迁移时间线。

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

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

对于从 Bitbucket Server 迁移，GitHub Enterprise Importer 仅迁移 Git 存储库和拉取请求。 任何其他资产（例如 CI 管道）都将保留在 Bitbucket Server 中。

由于 GitHub 中权限的使用方式与在 Bitbucket Server 中的不同，因此 GitHub Enterprise Importer 不会尝试从 Bitbucket Server 迁移存储库权限。 有关详细信息，请参阅“配置权限”。

  1. 查看从 Bitbucket Server 迁移的数据。 有关详细信息，请参阅“关于从 Bitbucket Server 迁移到 GitHub Enterprise Cloud”。
  2. 列出需要手动迁移或重新创建的所有数据。

谁将运行迁移？

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

还必须具有 Bitbucket Server 实例所需的权限和访问权限：

  • 管理员或超级管理员权限
  • 如果 Bitbucket Server 实例运行的是 Linux，则需要使用受支持的 SSH 私钥，以 SFTP 方式访问实例（请参阅《AUTOTITLE》）
  • 如果 Bitbucket Server 实例运行 Windows，则为对该实例的文件共享 (SMB) 访问权限
  1. 确定是否需要目标组织的组织所有者执行迁移，还是需要向其他人授予迁移者角色。
  2. 如果选择授予迁移者角色，请决定将向哪个人或团队授予该角色。
  3. 向个人或团队授予迁移者角色。 有关详细信息，请参阅“管理从 Bitbucket Server 迁移的访问权限”。
  4. 确认此人已正确配置 personal access token 以满足所有访问要求。 有关详细信息，请参阅“管理从 Bitbucket Server 迁移的访问权限”。
  5. 确认迁移者具有 Bitbucket Server 实例的管理员或超级管理员权限和 SFTP 访问权限。

我们需要 GitHub 的什么组织结构？

接下来，计划将在 GitHub 中创建的组织结构。

在 Bitbucket Server 中，存储库按项目分组。 在 GitHub 中，存储库归组织所有。 但是，最佳方法并非是在 GitHub 中为 Bitbucket Server 的每个项目创建一个组织。

迁移到 GitHub 后，应只有一个企业帐户和该企业拥有的少量组织。

每个迁移的存储库都归其中一个组织所有，这可能会导致每个组织内出现大量未分组的存储库。 但你可以在 GitHub 上创建团队来管理对存储库组的访问。 有关详细信息，请参阅“关于团队”。

如果要将迁移工作划分为多批进行，请考虑按组织进行批处理。

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

运行迁移

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

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

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

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

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

  1. 为试验性迁移创建测试组织。
  2. 运行试验性迁移。
  3. 完成下面所述的试验性迁移后续任务。
  4. 要求用户验证迁移结果。
  5. 解决试验性迁移发现的任何问题。
  6. 如果目标使用 IP 允许列表，请将列表配置为允许 GitHub Enterprise Importer 进行访问。 For more information，请参阅“管理从 Bitbucket Server 迁移的访问权限”。
  7. 运行生产迁移。 有关详细信息，请参阅“将存储库从 Bitbucket Server 迁移到 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 排查迁移问题”。 查看任何迁移警告后，需要决定是否可以接受这些警告并继续下一步操作。

设置存储库可见性

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

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

配置权限

由于 GitHub 中权限的使用方式与在 Bitbucket Server 中的不同，因此 GitHub Enterprise Importer 不会尝试从 Bitbucket Server 迁移存储库权限。

若要授予面向迁移存储库的访问权限，可以创建团队并为每个团队授予对存储库的访问权限。

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

回收模型

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

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

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

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

配置 IP 允许列表

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

有关详细信息，请参阅“管理从 Bitbucket Server 迁移的访问权限”。