规划迁移到 GitHub

关于迁移

如果您在 GitHub 产品之间迁移，例如从 GitHub Enterprise Server 迁移到 GitHub Enterprise Cloud，或从其他代码托管平台（如 Bitbucket Server 或 GitLab）迁移到 GitHub，您会希望将工作一起迁移：代码、代码的历史以及所有过去的对话和协作。

本指南将帮助您规划并成功执行迁移。您将了解如何为迁移做准备、可用的迁移工具以及如何确保迁移成功。

迁移术语

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

术语	定义
代码托管平台	您用于托管源码仓库并进行协作的在线工具，例如 GitHub Enterprise Cloud、GitHub Enterprise Server、Bitbucket Server 与 GitLab.com。
版本控制系统（VCS）	您在本机上用于跟踪和管理源码变更的工具。 例如，如果您使用 GitHub 或 GitLab 作为代码托管平台，则使用的是 Git 版本控制系统。如果您使用 Azure DevOps 作为代码托管平台，则底层版本控制系统可能是 Git 或 Team Foundation Version Control（TFVC）。也有可能根本没有使用 VCS。
迁移源	您要从哪里迁移。通常是代码托管平台，也可能是您自己的机器或共享网络磁盘。
迁移目标	您要迁移到的 GitHub 产品。
迁移路径	迁移源与迁移目标的组合，例如 “Bitbucket Server 到 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
• 最近更新时间戳
• Pull Request 数量（或迁移源中等效的概念）
• Issue 数量（或迁移源中等效的概念）

如果您从 GitHub Enterprise Cloud 或 GitHub Enterprise Server 迁移，可使用 GitHub CLI 的 gh-repo-stats 扩展获取上述数据。只需几条命令，gh-repo-stats 就会调用迁移源的 API 并生成包含所有推荐字段的 CSV。更多信息请参阅 mona-actions/gh-repo-stats 仓库。

如果您从 Azure DevOps 迁移，建议使用 GitHub CLI 的 ADO2GH 扩展中的 inventory-report 命令。该命令会调用 Azure DevOps API，生成一个包含上述部分字段的简易 CSV。有关安装 ADO2GH 扩展的详细信息，请参阅 从 Azure DevOps 迁移仓库到 GitHub Enterprise Cloud。

如果您从 Bitbucket Server 或 Bitbucket Data Center 迁移，建议使用 GitHub CLI 的 BBS2GH 扩展中的 inventory-report 命令。该命令会调用 Bitbucket 实例的 API，生成简易 CSV。有关安装 BBS2GH 扩展的详细信息，请参阅 从 Bitbucket Server 迁移仓库到 GitHub Enterprise Cloud。

对于其他迁移源，请自行创建迁移清单。可以使用源系统的报表工具（如果有）或 API 导出数据，或手动收集。

无论采用何种方式生成迁移清单，请记录所使用的过程或命令。随着迁移计划的推进，您很可能需要重新运行清单脚本。

获得全部仓库列表后，您可以决定要迁移哪些仓库。一种做法是迁移全部，但迁移也是审视并清理不再需要的仓库的好时机。我们发现很多组织拥有数百甚至上千个未使用的仓库，归档这些仓库可以大幅简化迁移工作。

衡量仓库的大小

完成基本清单后，收集仓库大小信息。如果仓库很大或包含超过 100 MB 的单个文件，迁移将更耗时、更具风险，并且可用的迁移工具也会受限。

如果您使用 Git 作为版本控制系统，不仅要关注仓库当前的文件大小，还要关注历史记录中的大文件。例如，过去曾有超过 100 MB 的文件存在于仓库中，则该文件仍然保留在 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。详情请参见 Download 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。
源、历史和元数据	迁移当前代码状态、修订历史以及协作历史（如 Issue、Pull Request）和设置等元数据。	需要专用工具，且并非所有迁移路径均提供该工具。

在决定采用哪种迁移类型时，请结合组织需求与可用工具进行权衡。

不同仓库可以采用不同策略。例如，部分已归档且无需保留历史的旧仓库可以使用低保真迁移，而最活跃的代码库则可能需要高保真迁移。

关于我们不同的迁移支持模式

您可以选择自行迁移（self‑serve migration），即仅使用文档自行规划并执行迁移，无需 GitHub 的专业支持。

或者，您也可以选择与 GitHub 专家服务团队或合作伙伴合作，进行“专家主导迁移（expert‑led migration）”。通过专家主导迁移，您可以受益于拥有丰富迁移经验的专家，并可使用自助迁移不可用的额外迁移工具。

如果迁移数据量大，建议使用专家主导迁移。例如，迁移成千上万的仓库或单个仓库超过约 5 GB 时，联系专家服务会更有帮助。

如需了解更多关于专家主导迁移的信息，请联系您的客户经理或 专家服务。

决定使用哪些工具

规划迁移时，请先考虑迁移目标和源。这些因素决定了迁移路径。更多信息请参阅 迁移路径概览。

为迁移目标设计组织结构

在 GitHub 中，每个仓库都属于一个组织。组织是企业或开源项目在多个仓库间协作的共享账号，具备高级的安全和管理功能。详情请参阅 关于组织。

无论是首次采用 GitHub，还是已经在使用 GitHub，都请思考迁移后组织与仓库的最佳结构。合理的设计可以提升协作与发现效率、降低管理负担；不恰当的设计则可能导致不必要的孤岛和管理开销。

我们建议将组织数量保持在最少，并按以下五种原型之一进行结构化。详见 企业组织结构最佳实践。

对每个仓库进行干运行迁移

在继续规划之前，请对所有仓库执行一次干运行迁移。全面的干运行可以帮助您：

• 确认所选工具能处理您的仓库
• 确认工具满足您的需求
• 明确哪些数据会被迁移、哪些不会被迁移
• 了解迁移所需时间，帮助您安排正式迁移的时间表

干运行迁移与正式迁移没有本质区别。只需像正常迁移一样执行，然后在迁移目标中删除该仓库即可。

规划迁移前后步骤

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

完整的迁移步骤取决于具体情况，但以下迁移前步骤适用于所有迁移：

• 提前通知用户即将进行的迁移及其时间表
• 在迁移前不久发送提醒
• 为团队在 GitHub 上创建用户账号
• 向用户发送指引，帮助他们将本地仓库指向新系统

同样，以下迁移后步骤适用于所有迁移：

• 通知用户迁移已完成
• 将活动关联到迁移目标中的用户
• 退役迁移源

以下是规划迁移时可考虑的其他步骤。

Migrating continuous integration (CI) and continuous delivery (CD)

如果您在 GitHub 产品之间迁移、已在使用 GitHub Actions 进行 CI/CD 且将继续使用 GitHub Actions，则几乎无需额外操作。仓库中的工作流文件会自动迁移。如果使用自托管 runner，则需要在新组织中重新配置，以便运行工作流。

如果未使用 GitHub Actions，情况会更复杂。如果计划继续使用同一 CI/CD 提供商，需要确认该提供商与 GitHub 的兼容性，并将其连接到新组织和仓库。

如果您计划切换到 GitHub Actions，我们不建议在同一次迁移中同时完成代码和 CI/CD 的迁移。请等到后续时间点，再单独进行 CI/CD 迁移，这样更易于管理。准备迁移时，请参考 迁移到 GitHub Actions。

Migrating integrations

您很可能已经在代码托管平台上使用了自建或第三方提供的集成。

如果已经在使用 GitHub，则需要重新配置这些集成指向新的组织和仓库。若集成由供应商提供，请联系供应商获取指引；若为内部开发，请在新组织中重新配置集成，生成新的令牌和密钥。

如果您是 GitHub 新手，请先确认现有集成是否兼容 GitHub，然后进行重新配置。内部开发的集成需改写为使用 GitHub API，详情请参阅 GitHub REST API 文档。

Linking activity to users in your migration destination

如果您迁移协作历史或元数据（如 Issue、Pull Request），则需要将用户活动关联到迁移目标中的新身份。

例如，假设 @octocat 在您原有的 GitHub Enterprise Server 实例中创建了 Issue，而您正迁移到 GitHub Enterprise Cloud。迁移后 @octocat 在 GitHub Enterprise Cloud 可能拥有完全不同的用户名。归属过程可以帮助您将用户活动映射到这些新身份。

不同工具的归属方式各有差异

• 如果使用 ghe-migrator、gl-exporter 或 bbs-exporter，需要事先决定归属策略，并在导入数据时提供映射文件。
• 如果使用 GitHub Enterprise Importer，数据会先关联到名为 “mannequins” 的占位身份，迁移完成后您可以将这些历史分配给真实用户。更多信息请参阅 为 GitHub Enterprise Importer 回收 mannequin。

Managing teams and permissions

大多数客户使用团队来管理仓库访问权限。使用团队后，您无需为每个用户单独授予仓库权限，只需将用户加入相应团队，然后为团队赋予仓库权限。详情请参阅 关于组织团队。

您可以在迁移仓库之前创建团队并添加成员。可以通过将团队与身份提供商（IdP）组关联，实现通过 IdP 管理成员。更多信息请参阅 将团队与身份提供商组同步。

但在迁移完成之前，您无法将团队绑定到仓库上。