规划迁移到 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（包括 GitHub Enterprise Cloud）或 GitHub Enterprise Server。

构建要迁移的仓库的基本清单

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

您应该构建一个迁移清单，其中列出迁移源中需要迁移的所有仓库。我们建议使用电子表格。作为起点，您应该为每个仓库记录以下数据

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

如果您从 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 命令。inventory-report 命令将连接到 Azure DevOps API，然后构建一个包含上面建议的一些字段的简单 CSV 文件。有关如何安装 GitHub CLI 的 ADO2GH 扩展的更多信息，请参阅 "从 Azure DevOps 迁移到 GitHub Enterprise Cloud 的存储库。"。

如果您从 Bitbucket Server 或 Bitbucket Data Center 迁移，我们建议使用 GitHub CLI 的 BBS2GH 扩展中的 inventory-report 命令。inventory-report 命令将使用您的 Bitbucket 实例的 API 来构建一个简单的 CSV 文件。有关如何安装 GitHub CLI 的 BBS2GH 扩展的更多信息，请参阅 "从 Bitbucket Server 迁移到 GitHub Enterprise Cloud 的存储库。"。

对于其他迁移源，请自己创建迁移清单。您可以使用源的报告工具（如果可用）或 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 文档中的 下载 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 合作伙伴（我们称之为“专家引导迁移”）合作。通过专家引导迁移，您可以从以前运行过数十甚至数百次迁移的专家的知识和经验中受益，并且您可以访问自助服务中不可用的其他迁移工具。

要详细了解专家主导的迁移，请联系您的帐户代表或 专家服务。

决定使用哪些工具

要规划迁移，请考虑目标和源。这些考虑因素决定了迁移路径。有关更多信息，请参阅“迁移到 GitHub 的路径”。

为迁移目标设计组织结构

在 GitHub 中，每个仓库都属于一个组织。组织是共享帐户，企业和开源项目可以在其中同时协作多个项目，并具有复杂的安全性管理功能。有关更多信息，请参阅“关于组织”。

无论您是首次采用 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，数据将链接到称为“模特”的占位符身份，您可以在数据迁移后将此历史记录分配给真实用户。有关更多信息，请参阅“为 GitHub Enterprise Importer 重新获取模特”。

管理团队和权限

大多数客户使用团队来管理对存储库的访问权限。使用团队，您可以将 Mona 添加到工程团队，并授予工程团队中的每个人对存储库的访问权限，而不是直接授予 Mona 对存储库的访问权限。有关更多信息，请参阅“关于团队”。

您可以在迁移存储库之前创建团队并添加团队成员。您可能希望通过将您的团队链接到 IdP 组来通过您的身份提供者 (IdP) 管理您的成员。有关更多信息，请参阅“将团队与身份提供者组同步”。

但是，您必须先迁移存储库，才能将团队附加到存储库。