导入和迁移群组和项目

要将既有项目导入极狐GitLab，或拷贝极狐GitLab 群组和项目到不同的位置，您可以：

  • 通过直接转移迁移极狐GitLab 区组和项目。
  • 从支持的导入源导入。
  • 从其他导入源导入。

使用直接转移从极狐GitLab 迁移到极狐GitLab

在极狐GitLab 实例间、同一个实例间拷贝群组的项目的最好方法是使用直接转移。

移动极狐GitLab 群组的另外一个选项是使用群组转移。

您还可以通过使用极狐GitLab 文件导出来拷贝极狐GitLab 项目。

支持的导入源

  • 极狐GitLab 私有化部署实例中，默认所有的导入器都是禁用的。此变更引入于极狐GitLab 16.0。

可用的导入源取决于您使用的极狐GitLab 实例：

  • JihuLab.com：所有的导入源默认启用。
  • 极狐GitLab 私有化部署实例：默认未启用导入源，必须要启用。

极狐GitLab 可以从支持的导入源导入项目：

导入源 描述
Bitbucket Cloud 使用Bitbucket.org 当作 OmniAuth 提供商功能，导入 Bitbucket 仓库。
Bitbucket Server 从 Bitbucket Server（也就是所谓的 Stash）导入项目。
FogBugz 从 FogBugz 导入项目。
Gitea 从 Gitea 项目导入。
GitHub 从 GitHub.com 或 GitHub 企业版导入。
GitLab export 通过使用极狐GitLab 导出文件来一个个迁移项目。
Manifest file 上传清单文件。
Repository by URL 提供一个 Git 仓库 URL 来创建新的项目。

禁用未使用的导入源

只从您信任的源导入项目。如果您从不信任的源导入项目，则攻击者可以偷盗您的敏感信息。比如，一个导入的项目，如果其中含有恶意的 .gitlab-ci.yml 文件，可能会让攻击者窃取群组的 CI/CD 变量。

极狐GitLab 私有化管理员可以通过禁用他们不需要的导入源来降低攻击面：

  1. 在左侧导航栏，底部，选择 管理员。
  2. 选择 设置 > 通用。
  3. 展开 导入和导出设置。
  4. 下拉到 导入源。
  5. 清除那些不需要的导入器前面的勾选框。

其他导入源

您还可以从其他导入源导入项目：

从 SVN 导入仓库

极狐GitLab 不能够自动将 Subversion 仓库转换为 Git。将 Subversion 仓库转换为 Git 可能很困难，但是有一些工具可以使用，包括：

  • git svn，针对一些非常小、基础的仓库。
  • reposurgeon，针对大切负责的仓库。

用户贡献和成员关系映射

  • 私有化部署实例的直接转移迁移引入于极狐GitLab 17.4，使用名为 importer_user_mapping 和 bulk_import_importer_user_mapping 功能标志。默认禁用。
  • 从 Gitea 导入项目引入于极狐GitLab 17.6，使用名为 importer_user_mapping 和 gitea_user_mapping 功能标志。默认禁用。
此功能的可用性受控于功能标志。更多详情，可以查看历史。

此用户贡献和成员关系映射功能在如下场景中对直接转移迁移可用：

  • JihuLab.com
  • 开启两个功能标志的极狐GitLab 私有化实例

有关在极狐GitLab 私有化部署实例且未启用功能标志时可用的其他方法的信息，查看用户贡献和成员关系映射。

使用用户贡献和成员资格映射，你可以在导入完成后将导入的贡献和成员资格分配给目标实例上的用户。与之前的用户贡献和成员资格映射方法不同，导入前无需进行准备工作。

该过程不依赖于电子邮件地址，因此你可以为源实例和目标实例上拥有不同电子邮件的用户映射贡献。

目标实例上每个被分配映射的用户可以：

  • 在任何导入的贡献被关联到他们前显示接受
  • 拒绝重新指派。

先决条件

  • 您必须能够创建足够的用户，但会受限于用户限制。
  • 如过导入到 JihuLab.com，在导入之前您必须设置您的付费命名空间。

占位用户

对于任何其贡献或成员资格已被导入的用户，不会立即将贡献和成员资格分配给目标实例上的用户，而是会为其创建一个占位符用户。

贡献和成员关系首先会被指派给占位用户，并且会在既有成员被导入到目标实例上后重新指派。

在它们被重新分配之前，贡献会显示为与占位符相关联。占位符成员资格不会显示在成员列表中。

例外

源实例上的每个用户都会创建一个展位用户，但在以下场景中除外：

  • 您正在从Gitea导入项目，而且用户在导入前在 Gitea 上已被删除了。这些 “ghost 用户”的贡献会被映射到导入的成员，而非占位用户。
  • 您已经超过了您的占位用户限制。超过限制之后，任何新用户的贡献都会被映射到单个导入用户上。

占位用户属性

占位用户有别于常规用户，而且不能够：

  • 登录。
  • 执行任何操作。比如，运行流水线。
  • 以指派者出现在建议中火出现在合并请求和议题的审核者中。

  • 成为项目或群组的成员。

  • 为了为何吃源实例上用户的连接，占位用户需要有：

  • 为导入流程所用的唯一识别码（source_user_id），以便决定是否需要新的占位用户。
  • 源主机名或域名（source_hostname）。
  • 源用户的名称（source_username）来帮助重新分配贡献。
  • 源用户的用户名（source_username) 来帮助群组拥有者重新分配贡献。
  • 一个导入类型（import_type）来区分哪个导入器创建了占位用户。

要查看历史内容，占位符用户名和用户账号是从源用户名和用户账号派生而来的。

  • 占位用户的名称是 Placeholder <source user name>。
  • 占位用户的用户名是 %{source_username}_placeholder_user_%{incremental_number}。

查看占位用户

先决条件：

  • 您必须拥有群组的拥有者角色。

当导入群组或项目时，占位用户会在目标实例上被创建出来。要想查看在导入顶级群组和其子群组时创建的占用用户，您可以：

  1. 在左侧导航栏，选择 搜索或前往 并找到您项目。
  2. 选择 管理 > 成员.
  3. 选择 占位 选项卡。

占位用户限制

每个导入源和每个顶级群组创建的占位用户为：

  • 如果您在目标实例上将同一个项目两次导入同一个顶级群组，第二次导入使用首次导入的占位用户。
  • 如果您在目标实例上将同一个项目导入两次，但是是不同的顶级群组，则第二次导入会在顶级群组下创建新的占位用户。

如果导入到 JihuLab.com，在目标实例的顶级群组上，占位用户会被限制。限制取决于您的计划和席位数量。占位用户不计入许可证限制。

JihuLab.com 计划 Number of seats Placeholder user limit on top-level group
免费和任意试用 Any amount 200
专业版 < 100 500
专业版 101-500 2000
专业版 501 - 1000 4000
专业版 > 1000 6000
旗舰版和开源 < 100 1000
旗舰版和开源 101-500 4000
旗舰版和开源 501 - 1000 6000
旗舰版和开源 > 1000 8000

传统的铜、银和金计划对应现在的免费、专业版或旗舰版限制。对于使用旗舰版功能的专业版客户（旗舰版试用）来讲，仅专业版限制生效。

如果这些限制不足以支持您的导入，您可以联系极狐GitLab 的技术支持。、

以上限制仅针对 JihuLab.com。私有化部署实例默认没有占位限制。私有化部署实例管理员可以为其安装设置占位限制。

重新指派贡献和成员关系

将占位用户的贡献和成员关系重新指派给既有的活跃（非机器人）用户发生在目标实例上。在目标实例上，您可以：

最初分配给单个占位符用户的所有贡献只能重新分配给目标实例上的单个活跃普通用户。分配给单个占位符用户的贡献不能拆分给多个活跃普通用户。

源实例上的机器人用户贡献和成员关系可以被重新指派给目标实例上的机器人用户。您可以选择保持将源机器人用户贡献指派给占位用户。

接受重新指派请求的用户可以：

  • 接受请求。之前指派给占位用户的所有贡献和成员关系都可以重新指派给接受的用户。此过程需要一些时间，这取决于贡献的数量。
  • 拒绝请求 或将其视为垃圾。此选项在重新指派请求邮件中可用。

在后续的导入中，属于同一源用户的贡献和成员资格会自动映射到之前接受该源用户重新分配的用户。

在您执行以下操作前，必需要确保重新指派流程已经完整完成：

如果流程没有完成，占位用户所拥有的贡献和成员关系将无法被重新指派给真实用户，它们会和占位用户保持关联。

安全考量

贡献和成员关系重新指派不能够被撤销，因此需要在开始之前一定要仔细检查。

重新指派贡献和成员关系到非正确用户会面临安全威胁，因为此用户会变成您的群组成员。因此，他们可以查看他们不应该看到的信息。

重新指派给具有管理员权限的用户功能是默认禁用的，但是您可以启用它。

成员关系安全考量

由于极狐GitLab 权限模型的缘故，当一个群组或项目被导入到一个现有的父群组中时，父群组的成员会被授予导入的群组或项目的继承成员资格。

选择一个用户进行贡献和成员资格重新分配，如果该用户已经拥有导入群组或项目的现有继承成员资格，可能会影响如何将成员资格重新指派给他们。

极狐GitLab 不允许子项目或群组上的成员关系所具有的角色比继承的成员关系低。如果已分配用户的导入成员资格的角色低于其现有的继承成员资格，则不会将导入的成员资格重新分配给该用户。

这会导致他们在导入的群组或项目中的成员资格级别高于其在源端的成员资格级别。

在 UI 上请求重新指派

先决条件：

  • 您必须要有群组的拥有者角色。

要请求一个用户接受贡献和成员关系的重新指派：

  1. 在左侧导航栏，选择 搜索或前往，并找到您的群组。
  2. 选择 管理 > 成员。1
  3. 选择 占位 选项卡。
  4. 前往 等待重新指派 子选项卡，这里面会列出占位用户列表。
  5. 在 重新指派占位给 一栏中，从下拉菜单中选择对应的用户。
  6. 选择 重新指派。

一个展位用户的贡献可以被重新指派给目标实例上一个活跃的非机器人用户。

在用户接受重新指派前，您可以取消请求。

保持占位

您也许不想将贡献和成员关系重新指派给目标实例上的用户。比如，您也许有前员工在源实例上做了贡献，但是他们已经不存在于目标实例上。

在这种情况下，您可以将贡献和成员关系指派给占位用户。占位用户不会持有成员关系信息因为他们不是项目或群组的成员。

由于占位符用户的姓名和用户名与源用户的姓名和用户名相似，索引您能保留大量的历史背景信息。

记住，如果您决定保留占位用户，之后您将无法将他们的贡献重新指派给实际用户。所以需要确保在您决定保留占位用户前需要完成所有的重新指派。

您可以一次保留一个占位用户，也可以批量处理

如要每次保留一个占位用户：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 管理 > 成员。
  3. 选择 占位 选项卡。
  4. 前往 等待重新指派 子选项卡，这里面会列出占位用户列表。
  5. 通过审核 占位用户 和 源 来找到您想保留的占位用户。
  6. 在 重新指派占位给 一栏中，选择 不重新指派。
  7. 选择 确认。

要想批量处理：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 管理 > 成员。
  3. 选择 占位 选项卡。
  4. 在靠近 用 CSV 指派 的地方选择 更多选项图标。
  5. 选择 保留所有占位 选项。
  6. 在确认页面，选择 确认。

取消重新指派请求

在用户接受重新指派请求前，您可以取消请求：

  1. 在左侧导航栏，选择 搜索或前往，并找到您的群组。
  2. 选择 管理 > 成员。
  3. 选择 占位 选项卡。
  4. 前往 等待重新指派 子选项卡，这里面会列出占位用户列表。
  5. 选择 取消。

再次通知用户关于重新指派请求等待的事情

如果用户在重新指派请求上没有做任何动作，您可以通过再次发送邮件来催促他们：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 管理 > 成员。
  3. 选择 占位 选项卡。
  4. 前往 等待重新指派 子选项卡，这里面会列出占位用户列表。
  5. 选择 通知。

通过重新指派状态来查看、过滤和排序

您可以查看重新指派流程未完成的所有占位用户的状态：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 管理 > 成员。
  3. 选择 占位 选项卡。
  4. 前往 等到重新指派 子选项卡，这里面会列出占位用户列表。
  5. 在 重新指派状态 一栏中查看每个占位用户的状态。

您可以通过重新指派状态进行过滤：

  1. 在过滤器下拉列表中，选择 状态。
  2. 选择一个可用的状态。

在 等到重新指派 选项卡中，可能的状态为：

  • Not started - 重新指派未开始。
  • Pending approval - 重新指派在等待用户审核。
  • Reassigning - 重新指派正在进行。
  • Rejected - 重新指派被用户拒绝。
  • Failed - 重新指派失败。

在 重新指派的 选项卡中，可能的状态为：

  • Success - 重新指派成功。
  • Kept as placeholder - 占位用户变为永久。

默认情况下，该表格按占位用户名称的字母顺序排序。您还可以按重新指派状态进行排序：

  1. 在排序下拉列表中选择。
  2. 选择 重新指派状态。

接受贡献的重新指派

您可能会接收到一封邮件，告知您导入流程正在发生并且询问您确认关于您自己的贡献重新指派。

如果您被告知此导入流程，您依旧必需仔细地审核重新指派详情。邮件中列出的详情有：

  • 从xx导入的 - 导入内容的源头平台。比如，另一个极狐GitLab 实例、GitHub 或 Bitbucket。
  • 原始用户 - 源平台的用户名和名称。这可能是在那个平台您自己的名称和用户名。
  • 导入到 - 导入内容的平台。比如，极狐GitLab。
  • 重新指派给 - 您在极狐GitLab 实例上的的完成名称和用户名。
  • 重新指派由 - 您的同事或经理的名称和用户名。

拒绝贡献重新指派

如果您收到一封邮件，让您确认贡献的重新指派，如果您不认可或者您任务里面有错误的话，您可以：

  1. 不要继续处理或拒绝贡献的重新指派。
  2. 告知可信任的同时或您的经理。

安全考量

您必须非常自己的审核任何重新指派请求的详情。如果未有受信任的同事或您的经理告知您此流程，您需要额外小心。

相比于直接接受任何指派，您需要对以下信息持怀疑状态：

  1. 不要在邮件中做操作。
  2. 告知可信任的同时或您的经理。

仅从您认识或信任的用户那边接受重新指派。贡献的重新指派是永久的，无法撤销。接受重新指派可能会导致不正确的贡献分配给您。

仅当您在极狐GitLab 上通过选择 审核重新指派 来接受重新指派请求后，贡献重新指派流程才会开始。流程不会通过选择邮件中的连接而开始。

查看项目导入历史

您可以查看所有您创建的导入项目。列表会包含如下内容：

  • 如果项目从外部系统导入，则包含源项目路径。
  • 目标项目的路径。
  • 每次导入的开始时间。
  • 每次导入的状态。
  • 如果出现任何错误，则有错误详情。

要查看导入历史：

  1. 登录极狐GitLab。
  2. 在左侧导航栏，顶部，选择 创建新的 ( ) 和 新的项目/仓库。
  3. 选择 导入项目。
  4. 在右上角，选择 历史 链接。
  5. 如果特定的导入出现错误，选择 详情 进行查看。

历史还包括从内置或自定义模板创建的项目。极狐GitLab 使用通过 URL 导入仓库来从模板创建新的项目。

导入具有 LFS 对象的项目

当导入包含 LFS 对象的项目时，如果项目有 .lfsconfig 文件，而且 URL 主机（lfs.url）和仓库 URL 主机不相同，则 LFS 文件不会被下载。

使用专业服务进行迁移

如果您更愿意使用专业服务来迁移您的群组和项目。您可以咨询极狐GitLab 的专业技术服务支持：

migration-services

Sidekiq 配置

导入器严重依赖 Sidekiq 作业来处理群组和项目的导入导出。有些作业可能会消耗大量的资源（CPU 和内存）并花费很长时间才能完成，这可能会影响其他的作业。为了解决此问题，您应该将导入器作业路由到专用的 Sidekiq 队列并分配一个专用的 Sidekiq 进程来处理该队列。

比如，您可以使用如下配置：

sidekiq['concurrency'] = 20

sidekiq['routing_rules'] = [
  # Route import and export jobs to the importer queue
  ['feature_category=importers', 'importers'],

  # Route all other jobs to the default queue by using wildcard matching
  ['*', 'default']
]

sidekiq['queue_groups'] = [
  # Run a dedicated process for the importer queue
  'importers',

  # Run a separate process for the default and mailer queues
  'default,mailers'
]

在此步骤中：

  • 一个专用的 Sidekiq 进程会处理通过导入器队列的导入和导出作业。
  • 其他的 Sidekiq 进程会处理所有其他的作业（默认的和邮件器队列）。
  • 所有的 Sidekiq 进程都会使用 20 个并发线程作为默认值。对于内存受限的环境，您可能需要减少此值。

如果您的实例有足够多的资源可以支持多个并发作业，您可以配置额外的 Sidekiq 进程来加速迁移。比如：

sidekiq['queue_groups'] = [
  # Run three processes for importer jobs
  'importers',
  'importers',
  'importers',

  # Run a separate process for the default and mailer queues
  'default,mailers'
]

有了这个步骤，多个 Sidekiq 进程会并发处理导入和导出作业，只要实例有足够的资源，就会加速迁移的进度。

对与 Sidekiq 进程的最大值，需要记住以下内容：

  • 进程的最大数不应该超过可用的 CPU 核数。
  • 每个进程可以使用 2 GB 的内存，所以请确保实例有足够的内存来处理额外的进程。
  • 每个进程添加一个数据库连接，作为 sidekiq['concurrency'] 中定义的线程数。

更多详情，可以查看运行多个 Sidekiq 进程和处理特定的作业类。

故障排除

导入的仓库丢失了分支

如果导入的仓库不包含源仓库的所有分支：

  1. 设置环境变量 IMPORT_DEBUG=true。
  2. 使用不同的群组、子群组或项目名称来重试导入。
  3. 如果有些分支依旧丢失，检查 importer.log（比如，使用 jq）。

Exception: Error Importing repository - No such file or directory @ rb_sysopen - (filename)

如果您试图导入一个仓库源代码的 .tar.gz 文件下载内容，就会出现该错误。

导入需要极狐GitLab 导出文件，而不是仓库的下载文件。

诊断长时间或失败的导入

如果您正在经历基于文件导入的长时间延迟或失败，特别是使用 S3 时，以下内容可以帮助识别错误的根因：

查看导入状态

查看导入状态：

  1. 使用极狐GitLab API 来检查受影响项目的导入状态。
  2. 查看响应以查找任何错误信息或状态信息，特别是 status 和 import_error 的值。
  3. 在响应中注意 correlation_id，因为它对将来的故障排查异常重要。

查看日志

搜索日志以查看相关信息：

对于私有化部署实例：

  1. 检查 Sidekiq 日志 和 exceptions_json 日志。
  2. 搜索与 RepositoryImportWorker 相关的日志，并从检查导入状态查看对应的 ID。
  3. 查看诸如 job_status、interrupted_count 和 exception 等字段。

对 JihuLab.com（仅限极狐GitLab 团队成员）：

  1. 使用 Kibana来搜索 Sidekiq 日志并使用如下查询：

    Target: pubsub-sidekiq-inf-gprd*

    json.class: "RepositoryImportWorker" AND json.correlation_id.keyword: "<CORRELATION_ID>"

    or

    json.class: "RepositoryImportWorker" AND json.meta.project: "<project.full_path>"

  2. 查看在私有化部署实例中提及的相同字段。

识别常规问题

对照以下常见问题检查在查看日志中收集到的信息：

  • 中断的作业：如果你看到一个 interrupted_count 或 job_status，则显示失败，导入任务可能已多次中断并被置于死队列中。
  • S3 链接：使用 S3 导入的话，在日志中查看与 S3 相关的错误消息。
  • 大型仓库：如果仓库非常大，导入可能会超时。再次场景中考虑使用直接转移功能。