规划到 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 版本控制 (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
• 上次更新时间戳
• 拉取请求数（或迁移源中的等效项数目）
• 问题数（或迁移源中的等效项数目）

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

如果是从 Azure DevOps 迁移，建议在 ADO2GH extension of the GitHub CLI 中使用 inventory-report 命令。 inventory-report 命令会连接 Azure DevOps API，并使用上面建议的一些字段生成简单的 CSV。 若要详细了解如何安装 ADO2GH extension of the GitHub CLI，请参阅“将存储库从 Azure DevOps 迁移到 GitHub Enterprise Cloud”。

如果是从 Bitbucket 服务器或 Bitbucket 数据中心迁移，建议在 BBS2GH extension of the GitHub CLI 中使用 inventory-report 命令。 inventory-report 命令会使用 Bitbucket 实例的 API 生成简单的 CSV。 若要详细了解如何安装 BBS2GH extension of the GitHub CLI，请参阅“将存储库从 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 合作伙伴合作，我们将其称为“专家引导式迁移”。 进行专家引导式迁移时，之前运行过数十甚至数百次迁移的专家的知识和经验将让你受益匪浅，而且你可以获取自助迁移不可用的其他迁移工具。

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

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

确定要使用的工具

若要规划迁移，请考虑目的地和源。 这些注意事项可以帮助确定迁移的路径。有关详细信息，请参阅“迁移到 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，则数据将链接到名为“mannequins”的占位符标识，并且你可在迁移数据后将此历史记录分配给实际用户。 有关详细信息，请参阅“回收 GitHub Enterprise Importer 的模型”。

管理团队和权限

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

在迁移存储库之前，可以创建团队并添加团队成员。 你可能需要通过将团队关联到标识提供者 (IdP) 组，来通过 IdP 管理成员。 有关详细信息，请参阅“将团队与身份提供程序组同步”。

但是，只有在迁移存储库后，才能将团队附加到存储库。