使用直接迁移迁移群组和项目

使用直接迁移迁移 GitLab 群组和项目：

1. 确保你满足 先决条件。
2. 查看 用户贡献和成员映射。
3. 连接源 GitLab 实例。
4. 选择要导入的群组和项目 并开始迁移。
5. 查看导入结果。

如果出现问题，你可以：

1. 取消 或 重试 迁移。
2. 查看 故障排除信息。

先决条件

使用直接迁移前，请满足以下先决条件。

网络和存储空间

• 实例或 GitLab.com 之间的网络连接必须支持 HTTPS。
• 防火墙不能阻止源 GitLab 实例和目标 GitLab 实例之间的连接。
• 源 GitLab 实例和目标 GitLab 实例的 /tmp 目录必须有足够的可用空间 来创建和解压已传输项目和群组的归档文件。

版本

为提高成功且高性能的迁移几率：

• 将源实例和目标实例都升级到 GitLab 16.8 或更高版本，以支持关系的批量导入和导出。 更多信息，请参见 epic 9036。
• 在尽可能晚的版本之间进行迁移，以获取错误修复和其他改进。

如果源实例和目标版本不同， 源实例的版本不能比目标实例早超过两个 minor 版本。 此要求不适用于从 GitLab.com 到 GitLab Dedicated 的迁移。

配置

• 确保 Sidekiq 已正确配置。
• 两个 GitLab 实例都必须由实例管理员在 应用程序设置中启用 通过直接迁移迁移群组。
• 你必须拥有源 GitLab 实例的 个人访问令牌：
  • 对于 GitLab 15.1 及更高版本的源实例，个人访问令牌必须 具有 api 范围。
  • 对于 GitLab 15.0 及更早版本的源实例，个人访问令牌必须 同时具有 api 和 read_repository 范围。
• 你必须在源实例和目标实例上拥有所需的权限。对于：
  • 大多数用户，你需要：
    • 源群组的 Owner 角色。
    • 目标命名空间中允许你 创建子群组 的角色。
  • 两个实例的管理员如果没有所需角色，可以使用 API 开始导入。
• 要导入项目代码片段，请确保代码片段在 源项目中已启用。
• 要导入存储在对象存储中的项目，你必须：
  • 配置 proxy_download。
  • 确保目标 GitLab 实例可以访问源 GitLab 实例的对象存储。
• 当源实例或群组的 创建项目的默认最低角色要求 设置为 无 时，你不能导入带项目的群组。如果需要，可以更改此设置：
  • 对于 整个实例。
  • 对于 特定群组。

用户贡献和成员映射

当 bulk_import_importer_user_mapping 禁用时，此用户贡献和成员映射方法适用于 GitLab Self-Managed。此功能标志默认启用。 有关 GitLab Self-Managed 和 GitLab.com 默认方法的信息，请参见 用户贡献和成员映射。

迁移期间永远不会创建用户。相反，源实例上用户的贡献和成员身份会 映射到目标实例上的用户。用户成员身份的映射类型取决于源实例上的 成员类型：

• 直接成员身份映射为目标实例上的直接成员身份。
• 继承成员身份映射为目标实例上的继承成员身份。
• 共享成员身份映射为目标实例上的直接成员身份，除非用户已有共享成员身份。 共享成员映射的完整支持已在 issue 458345 中提出。

在映射 继承和共享 成员身份时，如果用户 在目标命名空间中已有 更高角色 的成员身份， 则该成员身份将映射为直接成员身份。这确保成员不会获得 提升的权限。

在目标实例上配置用户

为确保 GitLab 正确映射源实例和目标实例之间的用户及其贡献：

1. 在目标 GitLab 实例上创建所需的用户。你只能在 GitLab Self-Managed 实例上使用 API 创建用户，因为这需要 管理员权限。当迁移到 GitLab.com 或 GitLab Self-Managed 时，你可以：
   • 手动创建用户。
   • 设置或使用你现有的 SAML SSO 提供商 并利用通过 SCIM 支持的 SAML SSO 组的用户同步。你可以 使用已验证的电子邮件域绕过 GitLab 用户帐户验证。
2. 确保用户在源 GitLab 实例上有 公开电子邮件，与目标 GitLab 实例上的任何确认电子邮件地址匹配。大多数 用户会收到一封要求他们确认电子邮件地址的邮件。
3. 如果用户已存在于目标实例上，并且你使用 GitLab.com 群组的 SAML SSO，所有用户必须 将他们的 SAML 身份链接到他们的 GitLab.com 帐户。

在 GitLab UI 或 API 中没有自动设置用户公开电子邮件地址的方法。如果你需要设置 大量用户帐户具有公开电子邮件地址，请参见 issue 284495 了解可能的解决方法。

连接源 GitLab 实例

在目标 GitLab 实例上，创建要导入到的群组并连接源 GitLab 实例：

1. 创建以下之一：
   • 新群组。在左侧边栏顶部，选择 Create new ( ) 和 New group。然后选择 Import group。
   • 新子群组。在现有群组页面上，可以：
     • 选择 New subgroup。
     • 在左侧边栏顶部，选择 Create new ( ) 和 New subgroup。然后选择 import an existing group 链接。
2. 输入 GitLab 实例的基本 URL。
3. 输入你的源 GitLab 实例的 个人访问令牌。
4. 选择 Connect instance。

选择要导入的群组和项目

授权访问源 GitLab 实例后，你将被重定向到 GitLab 群组导入器页面。在这里你可以看到连接的源实例上你拥有 Owner 角色的顶级群组列表。

如果你不想导入源实例的所有用户成员身份，请确保 Import user memberships 复选框未选中。例如，源实例可能有 200 个成员，但你可能只想导入 50 个成员。导入完成后，你可以向群组和项目添加更多成员。

1. 默认情况下，建议的群组命名空间与源实例中存在的名称匹配，但根据你的权限，你可以在继续导入任何群组之前选择编辑这些名称。群组和项目路径必须符合 命名规则，如有必要会进行规范化以避免导入失败。
2. 在要导入的群组旁边，选择：
   • Import with projects。如果此选项不可用，请参见 先决条件。
   • Import without projects。
3. Status 列显示每个群组的导入状态。如果你保持页面打开，它会实时更新。
4. 群组导入完成后，选择其 GitLab 路径以打开其 GitLab URL。

查看导入结果

要查看导入结果：

1. 转到 群组导入历史页面。
2. 要查看失败导入的详细信息，选择任何具有 Failed 或 Partially completed 状态的导入上的 Show errors 链接。
3. 如果导入具有 Partially completed 或 Complete 状态，要查看哪些项目已导入和未导入，选择 View details。

当你在 GitLab UI 中看到某些项目上有 Imported 徽章时，你也可以看到该项目已导入。

群组导入历史

你可以在群组导入历史页面上查看通过直接迁移迁移的所有群组。此列表包括：

• 源群组的路径。
• 目标群组的路径。
• 每个导入的开始日期。
• 每个导入的状态。
• 如果发生任何错误，则为错误详细信息。

要查看群组导入历史：

1. 登录 GitLab。
2. 在左侧边栏顶部，选择 Create new ( ) 和 New group。
3. 选择 Import group。
4. 在右上角，选择 View import history。
5. 如果特定导入有任何错误，选择 Show errors 查看详细信息。

取消正在运行的迁移

如需，你可以使用 REST API 或 Rails 控制台取消正在运行的迁移。

使用 REST API 取消

有关使用 REST API 取消正在运行的迁移的信息，请参见 取消迁移。

使用 Rails 控制台取消

要使用 Rails 控制台取消正在运行的迁移：

1. 在目标 GitLab 实例上启动 Rails 控制台会话。

2. 运行以下命令查找最后一个导入。将 USER_ID 替换为启动导入的用户 ID：

   bulk_import = BulkImport.where(user_id: USER_ID).last

3. 运行以下命令使导入及其所有关联项目失败：

   bulk_import.entities.each do |entity|
     entity.trackers.each do |tracker|
       tracker.batches.each(&:fail_op!)
     end
     entity.trackers.each(&:fail_op!)
     entity.fail_op!
   end
   bulk_import.fail_op!

取消 bulk_import 不会停止在源实例上导出项目的工作进程，但会阻止目标实例：

• 要求源实例导出更多项目。
• 向源实例进行其他 API 调用以进行各种检查和信息获取。

重试失败或部分成功的迁移

如果迁移失败，或部分成功但缺少项目，你可以重试迁移。要重试以下内容的迁移：

• 顶级群组及其所有子群组和项目，使用 GitLab UI 或 GitLab REST API。
• 特定子群组或项目，使用 GitLab REST API。