关于迁移
如果您要在 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 版本控制 (TFVC) 作为底层版本控制系统。您也可能根本不使用 VCS。 |
| 迁移源 | 您要从中迁移的位置。通常情况下，这将是一个代码托管平台，但也可能是您自己的机器或共享网络驱动器。 |
| 迁移目标 | 您要迁移到的 GitHub 产品。 |
| 迁移路径 | 迁移源和迁移目标的组合，例如“Bitbucket Server 到 GitHub Enterprise Cloud”。 对于某些迁移路径，GitHub 提供了专用工具（例如 GitHub Enterprise 导入器）来帮助您进行迁移。 |
定义您的迁移范围
在规划迁移之前，您需要了解要迁移的内容以及迁移时间。
定义您的源和目标
首先，确定需要从哪里移动数据。这通常（但并非总是）是一个代码托管平台。
您的代码托管平台可能是 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 迁移，则可以使用 GitHub CLI 的gh-repo-stats 扩展来获取此数据。只需几个命令，gh-repo-stats 就会连接到迁移源的 API 并创建一个包含所有推荐字段的 CSV 文件。有关更多信息，请参阅mona-actions/gh-repo-stats 仓库。
注意
gh-repo-stats 是一个第三方开源工具，不受 GitHub 支持团队的支持。如果您需要此工具的帮助，请在其仓库中打开一个问题。
如果您是从 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` 获取您存储库的此数据。
先决条件
- 安装 `git-sizer`。有关更多信息，请参阅 github/git-sizer 存储库。
- 要验证是否已安装 `git-sizer`，请运行 `git-sizer –version`。如果您看到类似 `git-sizer release 1.5.0` 的输出，则安装成功。
- 安装 `jq`。有关更多信息，请参阅 `jq` 文档中的 下载 jq。
- 要验证是否已安装 `jq`，请运行 `jq –-version`。如果您看到类似 `jq-1.6` 的输出，则安装成功。
使用 `git-sizer` 衡量存储库大小
- 要从迁移来源克隆您的存储库，请运行 `git clone --mirror`。
- 导航到您克隆存储库的目录。
- 要以字节为单位获取存储库中最大文件的大小，请运行 `git-sizer --no-progress -j | jq ".max_blob_size"`。
- 要以字节为单位获取存储库中所有文件的总大小，请运行 `git-sizer --no-progress -j | jq ".unique_blob_size"`。
- 将上一步的值添加到您的清单中。
关于迁移类型
运行迁移时，您可以采取三种方法，这些方法提供不同级别的迁移保真度。
| 迁移类型 | 定义 | 要求 |
|---|---|---|
| 源快照 | 迁移代码的当前状态（现状），但不包括任何修订历史记录。 | 对于每个来源和目标都是可能的，即使您的代码当前未在版本控制系统 (VCS) 中跟踪。 |
| 源和历史记录 | 迁移代码的当前状态及其修订历史记录。 | 如果您一直在使用 Git 或可以在迁移前转换为 Git 的版本控制系统跟踪您的更改，则可以实现。 |
| 源、历史记录和元数据 | 迁移代码的当前状态及其修订历史记录，以及您的协作历史记录（例如问题和拉取请求）和设置。 | 需要专用工具，并非所有迁移路径都提供这些工具。 |
在决定完成哪种类型的迁移时，请考虑您组织的需求和可用的工具。
您可能希望对不同的存储库使用不同的策略。例如，您可能有一些旧的存档存储库，其中历史记录并不重要，而对于您最活跃的代码，高保真度迁移至关重要。
关于我们不同的迁移支持模式
您可以选择完成“自助迁移”，您只使用我们的文档来计划和运行自己的迁移，而无需 GitHub 提供任何专业支持。
或者，您可能更愿意与 GitHub 的专家服务团队或 GitHub 合作伙伴（我们称之为“专家主导的迁移”）合作。通过专家主导的迁移，您可以从以前运行过数十次甚至数百次迁移的专家的知识和经验中受益，并且您可以访问自助服务中不可用的其他迁移工具。
如果您要迁移大量数据，您可能会从专家主导的迁移中受益。例如，如果您要迁移数千个存储库，或者您拥有大于约 5 GB 的复杂存储库，我们建议您联系专家服务。
| 自助服务 | 专家主导 | |
|---|---|---|
| 访问文档 | ||
| 访问 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) 管理您的成员。更多信息，请参见“将团队与身份提供商组同步”。
但是，您必须在迁移存储库之后才能将团队附加到存储库。