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

了解使用 GitHub Enterprise Importer 从 Bitbucket Server 迁移到 GitHub 的过程，从计划到实施，再到完成后续任务。

本文内容

概述

使用 GitHub Enterprise Importer，您可以按每个存储库为单位迁移到 GitHub Enterprise Cloud。有关更多信息，请参阅“关于 GitHub Enterprise Importer”。

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

计划您的迁移

要计划您的迁移，请自问以下问题。

我们需要多快完成迁移？

确定您的时间表，这将在很大程度上决定您的方法。确定时间表的第一步是了解您需要迁移的内容。

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

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

在您清点需要迁移的存储库后，您可以根据所需的时间表权衡您的库存数据。如果您的组织能够承受更高程度的变化，那么您也许能够一次迁移所有存储库，在几天内完成迁移工作。但是，您可能拥有无法同时迁移的各个团队。在这种情况下，您可能希望批量安排和交错迁移以适应团队的时间表，从而延长迁移工作。

  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（请参阅“从 Bitbucket Server 迁移的访问管理”）。
  • 如果您的 Bitbucket Server 实例运行 Windows，则访问实例的文件共享 (SMB)。
  1. 决定您是想让目标组织的组织所有者执行迁移，还是需要将迁移者角色授予其他人。
  2. 如果您选择授予迁移者角色，请决定要将该角色授予哪些人员或团队。
  3. 将迁移者角色授予该人员或团队。有关更多信息，请参阅“从 Bitbucket Server 迁移的访问管理”。
  4. 确认该人员已正确配置个人访问令牌以满足所有访问要求。有关更多信息，请参阅“从 Bitbucket Server 迁移的访问管理”。
  5. 确认迁移者拥有管理员或超级管理员权限，以及对 Bitbucket Server 实例的 SFTP 访问权限。

我们希望在 GitHub 中使用什么组织结构？

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

在 Bitbucket Server 中，存储库分组到项目中。在 GitHub 中，存储库由组织拥有。但是，您不应该认为最佳方法是为 Bitbucket Server 中的每个项目在 GitHub 中创建一个组织。

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

每个迁移的存储库都将由其中一个组织拥有，这可能会导致每个组织中出现大量的未分组存储库列表。但是，您可以通过在 GitHub 上创建团队来管理对存储库组的访问。有关更多信息，请参阅“关于团队”。

如果您想将迁移工作分成批次，请考虑按组织进行批处理。

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

运行迁移

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

试运行迁移有助于确定几项关键信息。

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

试运行不需要花费太多时间协调。GitHub Enterprise Importer 从不需要使正在迁移的存储库的用户停机。但是，我们建议在生产迁移期间停止工作，以确保在迁移期间不会创建新数据，否则这些数据将缺失在迁移的存储库中。这对于试运行而言并不重要，因此试运行可以随时进行。为了减少完成试运行迁移所需的时间，您可以将试运行的批次安排在一起。然后，这些存储库的用户可以在他们自己的时间验证结果。

我们建议创建一个测试组织，用作试运行迁移的目标。您可以为所有试运行使用单个组织，也可以为每个预期的目标组织创建一个测试组织。考虑在组织名称的末尾包含-sandbox，以阐明这些组织仅用于迁移验证，不用于生产。完成后，您可以删除测试组织。

  1. 为试运行迁移创建一个测试组织。
  2. 运行试运行迁移。
  3. 完成下面针对试运行迁移描述的后续任务。
  4. 请用户验证迁移的结果。
  5. 解决试运行迁移发现的任何问题。
  6. 如果您的目标使用 IP 允许列表，请配置该列表以允许 GitHub Enterprise Importer 访问。有关更多信息，请参阅“从 Bitbucket Server 迁移的访问管理”。
  7. 运行生产迁移。有关更多信息，请参阅“将存储库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud”。
  8. 可选：删除测试组织。

完成后续任务

每次迁移完成后，在存储库准备好工作之前，您需要完成一些其他任务。

检查迁移状态

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

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

  • 如果您使用 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 故障排除迁移”。查看任何迁移警告后，您需要决定是否可以接受这些警告并继续进行。

设置存储库可见性

默认情况下，所有存储库都以私有方式迁移，只有运行迁移的用户和组织所有者才能访问该存储库。如果您不希望存储库是私有的，请更改可见性。

  • 您可以使用--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 提交除外）都将归属于名为“模特”（mannequin）的占位符身份。

您可以使用 GitHub CLI 或浏览器将每个模特的历史记录重新归属于组织成员。如果您使用 GitHub CLI，则可以批量收回模特。更多信息，请参阅“GitHub Enterprise Importer 的模特回收”。

注意

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

  1. 决定是否要收回模特。
  2. 规划何时完成回收。
  3. 回收模特。
  4. 如果任何成员尚未通过团队成员身份获得对仓库的适当访问权限，请授予成员对仓库的访问权限。更多信息，请参阅“管理个人对组织仓库的访问权限”。

配置 IP 允许列表

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

更多信息，请参阅“从 Bitbucket Server 迁移的访问管理”。