规划到 GitHub 的迁移

规划和执行成功迁移到产品或产品之间的GitHub迁移GitHub。

在本文中

关于迁移

如果要在 GitHub 产品之间移动（例如，从 GitHub Enterprise Server 到 GitHub Enterprise Cloud，或者从 Bitbucket Server 或 GitLab 等其他代码托管平台移动到 GitHub，则需要随身携带你的工作：你的代码、代码的历史记录以及过去所有的对话和协作。

本指南将帮助你规划和执行成功的迁移。 你将了解如何做好迁移准备，了解可用于移动数据的工具，并学习如何成功执行迁移。

迁移术语

在使用本指南规划迁移之前，请先了解下面的重要术语。

术语定义
代码托管平台用于托管源代码存储库和协作的联机工具，例如 GitHub Enterprise Cloud， GitHub Enterprise ServerBitbucket 服务器和 GitLab.com。
版本控制系统 (VCS)该工具用于在对源代码进行更改的计算机上跟踪和管理这些更改。

例如，如果使用 GitHub GitLab 作为代码托管平台，则使用 Git 版本控制系统。 如果使用 Azure DevOps 作为代码托管平台，你可以将 Git 或 Team Foundation 版本控制 (TFVC) 用作基础版本控制系统。 也有可能你根本没有使用 VCS。
迁移源要从其进行迁移的位置。 通常，这将是一个代码托管平台，但它也可能是你自己的计算机或共享网络驱动器。
迁移目标你正在迁移到的 GitHub 产品。
迁移路径迁移源和迁移目标的组合，例如“Bitbucket 服务器到 GitHub Enterprise Cloud”。

对于某些迁移路径， GitHub 提供专家工具，例如 GitHub Enterprise Importer，帮助你迁移。

定义迁移范围

你需要先了解要迁移的内容和迁移时间，然后才能规划迁移。

定义源和目标

首先，确定需要从何处移动数据。 这通常是代码托管平台，但并非总是如此。

代码托管平台可能是 GitHub 产品，例如 GitHub.com 或 GitHub Enterprise Server，也可能是另一个代码托管平台，例如 Bitbucket Server、GitLab 或 Azure DevOps。 根据业务的规模和复杂程度，你可能使用多个不同的代码托管平台。

例如，如果你根本没有使用代码托管平台，那么你可能是将代码存储在共享网络驱动器上。

无论你的代码位于何处，它都是你的“迁移源”。

还需要知道要迁移到哪个 GitHub 产品或“迁移目标”。 可以是 GitHub.com， GHE.com也可以 GitHub Enterprise Server。

生成要迁移的存储库的基本清单

确定迁移源和目标后，确定需要迁移的数据。

应创建一个迁移清单，其中列出了迁移源中所有需要迁移的存储库。 建议使用电子表格。 首先，应为每个存储库记录以下数据：

  • 名称
  • 所有者：在 GitHub，这将是一个组织，但在其他工具中，可能有不同的所有者类型
  • URL
  • 上次更新时间戳
  • 拉取请求数（或迁移源中的等效项数目）
  • 问题数（或迁移源中的等效项数目）

如果您从GitHub Enterprise Cloud或GitHub Enterprise Server迁移，可以使用针对gh-repo-stats的GitHub CLI插件获取此数据。 只需几个命令，gh-repo-stats 即可连接到迁移源的 API，并创建包含所有建议字段的 CSV。 有关详细信息，请参阅 mona-actions/gh-repo-stats 存储库。

注意

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

如果要从 Bitbucket 服务器或 Bitbucket 数据中心进行迁移，我们建议在inventory-report中使用BBS2GH extension of the GitHub CLI命令。 inventory-report 命令会使用 Bitbucket 实例的 API 生成简单的 CSV。 有关如何安装 BBS2GH extension of the GitHub CLI的详细信息，请参阅 将存储库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud。

根据迁移路径，可以使用各种工具来收集此数据：

  • 如果源是另一个GitHub产品，则为第GitHub CLI三方gh-repo-stats扩展。
  • 如果源是 Azure DevOps、GitLab 或 Bitbucket，则为 <Azure DevOps、GitLab 或 Bitbucket。</Azure DevOps。
  • 对于其他迁移源，可以使用源的报告工具或 API 生成电子表格，也可以手动创建清单。

有关使用这些工具的详细信息，请参阅我们的文档中的特定迁移路径。

无论为迁移清单选择哪种方法，都请记下所遵循的过程或运行的命令。 在你继续规划迁移时，很可能需要重新运行清单。

获得所有存储库的列表后，可以决定要迁移哪些存储库。 一种选择是迁移所有内容。 不过，迁移是评估存储库并移除不再需要的任何存储库的绝佳机会。 我们发现，许多企业都有数百甚至数千个未使用和不需要的存储库，将这些存储库存档可以使迁移更加简单。

测量存储库的大小

完成基本迁移清单后，请收集有关存储库大小的信息。 如果存储库较大或包含超过 100MB 的单个文件，那么迁移时间可能更长、风险更大，并且可能限制你可使用的迁移工具。

如果使用 Git 作为版本控制系统，那么不仅是存储库中当前存在的大文件很重要，存储库历史记录中的大文件也很重要。 例如，如果过去存储库中有文件大于 100MB，则该文件仍然将存在于 Git 历史记录中，除非你已重写历史记录来移除文件的所有跟踪。 若要详细了解如何重写历史记录，请参阅“关于 GitHub 上的大文件”。

如果使用了 gh-repo-stats 来生成清单，那么你已经获得有关存储库大小的一些基本信息。 要生成完整的迁移清单，需要获取有关存储库内数据的更详细细节。

接下来，按照以下说明将以下数据添加到每个存储库的迁移清单：

  • 最大文件（也称为“blob”）的大小
  • 所有文件（“blob”）的总大小

如果使用的是 Git 以外的版本控制系统，或者根本没有使用版本控制系统跟踪文件，请先将存储库移动到 Git。 有关详细信息，请参阅“将本地托管代码添加到 GitHub”。

然后，使用开源工具 git-sizer 获取存储库的此数据。

先决条件

  1. 安装 git-sizer。 有关详细信息，请查看 github/git-sizer 存储库。
  2. 要验证是否已安装 git-sizer，请运行 git-sizer –version。 如果看到类似于 git-sizer release 1.5.0 的输出，表示安装成功。
  3. 安装 jq。 有关详细信息，请参阅 文档中的jq。
  4. 要验证是否已安装 jq，请运行 jq –-version。 如果看到类似于 jq-1.6 的输出，表示安装成功。

使用 git-sizer 测量存储库大小

  1. 要从迁移源克隆存储库，请运行 git clone --mirror。
  2. 导航到克隆存储库的目录。
  3. 要获取存储库中最大文件的大小（以字节为单位），请运行 git-sizer --no-progress -j | jq ".max_blob_size"。
  4. 要获取存储库中所有文件的总大小（以字节为单位），请运行 git-sizer --no-progress -j | jq ".unique_blob_size"。
  5. 将前面步骤中的值添加到清单中。

关于迁移类型

运行迁移时可采用三种方法，这些方法提供不同级别的迁移保真度。

迁移类型定义要求
源快照像现在一样迁移代码的当前状态，但不包括任何修订历史记录。适用于每个源和目标，即使代码当前未在版本控制系统 (VCS) 中跟踪也是如此。
来源和历史记录迁移代码的当前状态及其修订历史记录。如果您已在 Git 中进行更改记录，或者在迁移前使用的是可转换为 Git 的版本控制系统，就可以实现这一点。
源、历史记录和元数据迁移代码的当前状态及其修订历史记录，还迁移协作历史记录（例如问题和拉取请求）以及设置。需要专业工具 - 并非所有迁移路径都可用。

在确定要完成的迁移类型时，请考虑组织的需求和可用的工具。

你可能想要对不同的存储库使用不同的策略。 例如，你可能有一些旧的存档存储库，其中历史记录并不重要，而高保真迁移对于最活跃的代码来说至关重要。

关于不同的迁移支持模型

可以选择完成“自助迁移”，在该迁移中，你仅使用我们的文档规划和运行自己的迁移，而无需任何 GitHub专业支持。

或者，你可能更喜欢与 GitHub'专家服务团队或 GitHub 合作伙伴合作，我们称之为“专家主导的迁移”。 进行专家引导式迁移时，之前运行过数十甚至数百次迁移的专家的知识和经验将让你受益匪浅，而且你可以获取自助迁移不可用的其他迁移工具。

如果要迁移大量数据，你可能会从专家主导的迁移中获益。 例如，如果要迁移数千个存储库，或者拥有大小超过 5 GB 的复杂存储库，建议与专家服务连接。

自助专家指导
访问文档
访问 GitHub的全套工具
支持涵盖的主题
  • 执行
  • 故障排除
  • 规划
  • 执行
  • 故障排除
成本免费有关详细信息，请联系专家服务

若要详细了解专家引导式迁移，请联系你的客户代表或专家服务。

确定要使用的工具

若要规划迁移，请考虑目的地和源。 这些注意事项可以帮助确定迁移的路径。 有关详细信息，请参阅 迁移到 GitHub 的路径。

为每个存储库执行试运行迁移

在继续规划之前，请执行试运行迁移（包括所有存储库）。 全面的试运行使你能够：

  • 验证所选工具是否适合你的存储库
  • 确认该工具满足你的要求
  • 确切了解迁移的数据和未迁移的数据
  • 了解迁移需要多长时间，以帮助你规划生产迁移

试运行迁移没有什么独特之处。 只需运行正常迁移，然后删除迁移目标中的存储库即可。

规划迁移前和迁移后的步骤

迁移存储库只是更大的迁移过程中的一个步骤。 还需要执行其他步骤，可能需要手动迁移数据或设置。

迁移所需的步骤的完整列表将根据你的独特情况决定，但迁移前有一些步骤适用于所有迁移：

  • 让用户提前了解即将进行的迁移及其时间线
  • 在迁移发生前不久发送提醒
  • 在GitHub为您的团队设置用户账户
  • 向用户发送说明，指导他们更新其本地存储库来指向你的新系统

也有适用于所有迁移的迁移后步骤：

  • 让用户知道迁移已完成
  • 将活动关联到迁移目标中的用户
  • 解除迁移源的授权

下面是规划迁移时应考虑的其他一些步骤。

迁移持续集成 (CI) 和持续交付 (CD)

如果你在 GitHub 产品之间迁移，已使用 GitHub Actions 进行 CI/CD，并且将继续使用 GitHub Actions，那么要做的事情不多。 存储库中的工作流文件将为你自动迁移。 如果你使用自托管运行器，则需要在新的 GitHub 组织中设置这些运行器，以便它们准备好运行你的工作流。

如果不使用 GitHub Actions，情况会更加复杂。 如果计划继续使用同一 CI/CD 提供程序，则需要检查提供程序是否与 GitHub该提供程序兼容，并将提供程序连接到新的组织和存储库。

如果打算切换到 GitHub Actions，我们建议不要在迁移存储库的同时执行此操作。 相反，请等待稍后再进行操作，并作为单独步骤执行 CI/CD 迁移。 这样，迁移过程就会更容易管理。 做好迁移准备后，请参阅“迁移到 GitHub Actions”。

迁移与整合

你很可能在使用与代码托管提供程序的集成，这些集成要么是内部开发的，要么由其他供应商提供的。

如果已在使用 GitHub，则需要重新配置集成，以指向新的组织和存储库。 如果集成由供应商提供，请联系该供应商来获取说明。 如果集成是在内部开发的，请在新组织中重新配置集成，生成新的令牌和密钥。

如果不熟悉 GitHub，请检查集成是否兼容 GitHub，然后重新配置它们。 如果使用内部开发的集成，请重新编写它们以使用 GitHub API。 有关详细信息，请参阅“GitHub REST API 文档”。

将活动与迁移目的地的用户关联起来

如果要迁移协作历史记录/元数据和代码，需要将用户的活动关联到他们在迁移目标中的新标识。

例如，假设 @octocat 在 你的 GitHub Enterprise Server 实例 上创建了一个问题，而你正在迁移到 GitHub Enterprise Cloud。 在GitHub Enterprise Cloud中，@octocat的用户名可能完全不同。 通过归因过程，可以将用户活动与这些新标识相关联。

归因的工作方式因工具而异：

  • 如果使用 ghe-migrator、gl-exporter 或 bbs-exporter，则需要提前确定如何进行数据归因，并在导入数据时包括映射文件。
  • 如果你使用 GitHub Enterprise Importer 或 Enterprise Live Migrations，数据将链接到名为“mannequins”的占位符标识，并且在数据迁移后，你可以将此历史记录分配给真实用户。 有关详细信息，请参阅“回收 GitHub Enterprise Importer 的模型”。