• 预估导入时长
• 先决条件
  • 权限和角色
  • 用户账号的贡献映射
• 已知问题
• 导入 GitHub 仓库到极狐GitLab
  • 使用 GitHub OAuth
  • 使用 GitHub 个人访问令牌
  • 使用 API
  • 过滤仓库列表
  • 选择额外的条目来导入
  • 选择导入哪些仓库
  • 检查导入的状态
• 镜像仓库并共享流水线状态
• 在私有化部署实例上提高导入速度
  • 增加 Sidekiq 工作器的数量
  • 使用 GitHub Enterpriese Cloud App 来启用 GitHub OAuth
• 导入的数据
  • 分支保护规则和项目设置
  • 协作者（成员）
• 在内部网络的 GitHub Enterprise 导入
  • 反向代理配置示例
• 极狐GitLab 技术支持

将您的项目从 GitHub 导入极狐GitLab

• 引入于极狐GitLab 15.8，极狐GitLab 不再自动化创建不存在的命名空间或群组。如果命名空间和群组被占用，极狐GitLab 也将不会回滚至使用用户个人的命名空间。
• 引入于极狐GitLab 15.10，您不再需要添加任何用户到父群组来成功导入 合并之前需要拉取请求 - 允许指定的操作者来绕过必须的拉取请求 分支保护规则。
• 导入条目上的 导入的 徽章引入于极狐GitLab 17.2。

您可以冲 GitHub.com 或 GitHub 企业版导入您的 GitHub 项目。导入项目并不会从 GitHub 迁移或导入任何类型的群组或组织到极狐GitLab。

导入的议题、合并请求、评论和事件在极狐GitLab 中都有 导入的 徽章。

在极狐GitLab 中，命名空间是用户或群组，比如 jihulab.com/sidney-jones 或 jihulab.com/customer-success。

使用极狐GitLab UI，GitHub 导入器宗师从 github.com 域名导入。如果您是从自托管的 GitHub 企业版服务器域名导入，可以使用GitHub 导入 API 端点。

在您导入之前，您可以修改目标命名空间和目标仓库名称。

预估导入时长

从 GitHub 的每一个导入都不同，这会影响您导入项目所需的时间。但是，在我们的测试中，我们导入 https://github.com/kubernetes/kubernetes 项目需要 76 小时。测试时，该项目包含：

• 80,000 拉取请求。
• 45,000 议题。
• 接近 150万评论。

先决条件

要从 GitHub 导入项目，您必须启用GitHub导入源。如果导入源未启用，寻求管理员的帮忙以启用它。在 JihuLab.com 上 GitHub 导入源默认启用。

权限和角色

• 需要维护者角色而不是开发者角色引入于极狐GitLab 16.0，并后向兼容 15.11.1 和 15.10.5。

要使用 GitHub 导入器，您必须有：

• GitHub 项目的访问权限，以便导入。
• 至少是极狐GitLab 目标群组的维护者角色。

另外，GitHub 仓库所属的组织不得对您要导入的 GitLab 实例施加第三方应用访问策略限制。

用户账号的贡献映射

要想让 GitHub 和极狐GitLab 之间的用户贡献生效：

• GitHub 仓库中的每个作者和指派者都必须要有公共邮箱。
• GitHub 用户的邮箱必须要和极狐GitLab 的邮箱相匹配。
• 如果用户在 GitHub 中的邮箱地址被设置为极狐GitLab 中的第二邮箱地址，则必须要确认这件事情。

GitHub 企业版不要求公共邮件地址，因此您可能需要将其添加到既有账号中。

如果不满足以上要求，导入器就不能够映射特定用户的贡献。在这种情况下：

• 项目创建者会被设定为作者以及议题和合并请求的指派者。项目创建者通常是初始化导入流程的用户。对于一些有描述或注释的贡献，比如合并请求、议题、注释，则导入器会以文本的形式添加最初创建该贡献的人员的详细信息。
• GitHub 拉取请求上的审核者和审批者不能够被导入。在这种情况下，导入器会创建注释，说明不存在的用户被添加为审核者和审批者。不过，实际的审核者状态和审批并不会应用到极狐GitLab 中的合并请求上。

在极狐GitLab 17.5 及以后版本中，极狐GitLab 会在议题、合并请求和笔记中的用户名提及处添加反引号。这些反引号可防止链接到极狐GitLab 实例上具有相同用户名的错误用户。

已知问题

• GitHub 中拉取请求评论（极狐GitLab 中的差异注释），如果是创建于 2017 年之前，则会以单独的线程导入。
• 因为已知问题，GitHub 企业版服务器实例上仓库中的 Markdown 附件不会被导入。
• 因为已知问题，当导入使用 GitHub 自动合并的项目时，如果提交是用 GitHub 内部 GPG 密钥签名的，那么导入到极狐GitLab 中的项目的合并提交可能会被标记为 “未验证” 。
• 极狐GitLab 不能够导入 2023-05-09 之前上传到私有仓库中的 GitHub Markdown 图片附件。

• 针对 极狐GitLab 特定引用，极狐GitLab 为议题使用 # 字符，为合并请求使用 ! 字符。然而，GitHub 为议题和拉取请求均使用 # 字符。当导入时：

  • 评论注释，极狐GitLab 仅为议题创建链接，因为极狐GitLab 无法决定引用是否指向议题还是合并请求。
  • 议题或合并请求描述，极狐GitLab 不能够为任何引用创建链接，因为它们对应的导入项可能尚未在目标位置创建。

导入 GitHub 仓库到极狐GitLab

您可以通过如下方式导入 GitHub 仓库：

• 使用 GitHub OAuth
• 使用 GitHub 个人访问令牌
• 使用 API

如果从 github.com 导入，则您可以使用任意方式来导入。私有化部署的 GitHub 企业版服务器客户则必须使用 API。

使用 GitHub OAuth

如果您正在从 JihuLab.com 或配置了 GitHub OAuth 的极狐GitLab 实例导入，您可以使用 GitHub OAuth 来导入您的仓库。

此方法比使用个人访问令牌（PAT）有优势，因为后端会用具有相应权限的访问令牌进行交换。

1. 在左侧导航栏，顶部，选择 创建新的 () 和 新项目/仓库。
2. 选择 导入项目 然后选择 GitHub。
3. 选择 用 GitHub 认证。
4. 继续选择要导入的项目。

如果在之前执行过这些步骤之后，想要使用不同的方法来执行导入操作，请先退出您的极狐GitLab 账户，然后再次登录。

使用 GitHub 个人访问令牌

要使用 GitHub 个人访问令牌导入 GitHub 仓库，请执行以下步骤：

1. 生成一个 GitHub 个人访问令牌。仅支持经典个人访问令牌。
   1. 前往 https://github.com/settings/tokens/new。
   2. 在 注释 字段，输入令牌描述。
   3. 选择 repo 范围。
   4. 可选。要导入协作者，或如果您的项目有Git LFS 文件，则选择 read:org 范围。
   5. 选择 生成令牌。
2. 在极狐GitLab 左侧导航栏，顶部，选择 创建新的 () and 新项目/仓库。
3. 选择 导入项目，然后选择 GitHub。
4. 选择 用 GitHub 认证。
5. 在 个人访问令牌 字段，粘贴 GitHub 个人访问令牌。
6. 选择 授权认证。
7. 继续选择要导入的仓库。

在先前执行过这些步骤之后，如果要使用不同的令牌来执行导入操作，需退出极狐GitLab 账户并再次登录，或者在 GitHub 中撤销旧令牌。

使用 API

极狐GitLab REST API可以被用来导入 GitHub 仓库。这比使用极狐GitLab UI 有一些优势：

• 可被用来导入您不拥有的 GitHub 仓库（如果是公共仓库）。
• 可以用来从私有化部署的 GitHub 企业版服务器导入仓库。
• 可被用来设置 UI 上不可用的 timeout_strategy 选项。

REST API 仅限于使用极狐GitLab 个人访问令牌进行身份验证。

要使用极狐GitLab REST API 导入您的 GitHub 仓库：

1. 生成一个 GitHub 个人访问令牌。仅支持 典型的 个人访问令牌。
   1. 前往 https://github.com/settings/tokens/new。
   2. 在 注释 字段，输入令牌描述。
   3. 选择 repo 范围。
   4. 可选。要导入协作者，或如果您的项目有Git LFS 文件，则选择 read:org 范围。
   5. 选择 生成令牌。
2. 使用极狐GitLab REST API 来导入您的 GitHub 仓库。

过滤仓库列表

• 引入于极狐GitLab 16.0。

在您使用令牌和 GitHub 认证后，极狐GitLab 会将您重定向至导入页面，其中列出了您的 GitHub 仓库。

使用如下的选项来过滤仓库列表：

• 拥有者（Owner）：列出您拥有的仓库列表。
• 协作者（Collaborated）：列出您参与过的仓库列表。
• 组织（Organization）：列出您是组织成员的仓库列表。

当选择 组织 时，您可以通过从下拉列表中选择一个可用的 GitHub 组织，进一步缩小搜索范围。

选择额外的条目来导入

• 引入于极狐GitLab 15.5。
• 将协作者作为额外的条目导入引入于极狐GitLab 16.0。
• 功能标志 github_import_extended_events 引入于极狐GitLab 16.8。默认禁用。此标志提升了导入性能，但是移除了 导入议题和合并请求事件 选项。
• 功能标志 github_import_extended_events 在 JihuLab.com 和私有化部署上启用于极狐GitLab 16.9。
• 改善导入性能在极狐GitLab 16.11 中 GA。功能标志 github_import_extended_events 被移除。

要想导入更快，默认情况下如下条目不会从 GitHub 导入：

• 超过 30,000 的评论，因为 GitHub API 的限制。
• 从仓库评论、版本文章、议题描述和拉取请求中的 Markdown 附件。这些内容可能包括图片、文本或二进制附件。如果未导入，当您从 GitHub 移除附件后，链接到附件上的 Markdown 会失效。

您可以选择导入这些条目，但是这些可能会增加导入时间。要导入这些条目，在 UI 上选择相近的字段：

• 使用可选地评论导入方法。如果要导入的 GitHub 项目具有超过 30,000 个评论（所有议题和拉取请求中的），您应该启用此方法，因为 GitHub API 限制。
• 导入 Markdown 附件。
• 导入协作者 （默认选择的）。保持选中状态可能会导致新用户占用群组或命名空间中的一个席位，并被授予 与项目拥有者同样高的权限（见 “协作者与成员” 部分）。仅直接协作者会被导入，外部协作者永远不会被导入。

选择导入哪些仓库

• 取消等待或活跃导入的能力引入于极狐GitLab 15.7。
• 重新导入项目的能力引入于极狐GitLab 15.9。

默认情况下，提议的仓库命名空间和 GitHub 中既有的名称相匹配，但是基于您的权限，您可以在继续导入之前编辑这些名称。

要选择导入的仓库，在仓库数量边上选择 导入 或选择 导入所有仓库。

此外，您还可以通过名称过来项目。如果使用了过滤器，导入所有的仓库仅导入匹配的仓库。

状态 一栏显示导入的状态。您可以选择保持页面打开并实时查看更新，或者稍后再返回。

要取消处于等待状态或正在进行中的导入，在导入的项目附近，选择 取消。如果导入已经启动，导入的文件将被保留。

要想在导入完成后打开极狐GitLab 仓库 URL，可选择它的极狐GitLab 路径。

可以通过选择 重导入 并指定新的名称来完成重导入。这会增加一个源项目的新副本。

检查导入的状态

• 部分导入时，失败条目的列表详情引入于极狐GitLab 16.1。

导入完成后，它们可能处于以下三种状态中的一种：

• 完成：极狐GitLab 导入了所有的仓库主体。
• 部分完成：极狐GitLab 在导入部分仓库主体是发生了失败。
• 失败：在严重错误发生后，极狐GitLab 中止了导入。

展开 详情 可以看到导入失败的仓库主体列表。

镜像仓库并共享流水线状态

取决于您的极狐GitLab 付费计划（专业版或旗舰版），可以设置仓库镜像来保持导入项目和 GitHub 仓库之间的同步。

此外，您还可以通过 GitHub 项目集成配置来将极狐GitLab 的流水线状态更新发送给 GitHub。

如果您导入了为外部仓库使用 CI/CD 的仓库，则上述内容会自动配置。

在私有化部署实例上提高导入速度

极狐GitLab 服务器上的管理员需要执行这些步骤。

增加 Sidekiq 工作器的数量

对于大型仓库，要导入所有数据会花费一段时间。为了减少所需时间，您可以增加 Sidekiq 工作器的数量来处理以下队列：

• github_importer
• github_importer_advance_stage

对于优化经验来说，推荐的做法是至少要有 4 个 Sidekiq 进程（每一个进程要运行和 CPU 核数相同的线程）来 仅 处理这些队列。还推荐将这些进程运行在独立的服务器上。对于具有 8 个核的 4 个服务器来说，这意味着您可以并行导入 32 个对象（比如议题）。

可以通过增加网络带宽、CPU 容量和磁盘性能（比如，使用高性能的 SSD）来减少克隆仓库所花费的时间。增加 Sidekiq 工作器的数量并 不能 减少克隆仓库所需的时间。

使用 GitHub Enterpriese Cloud App 来启用 GitHub OAuth

如果您属于一个 GiHub Enterprise Cloud 组织，则您可以配置您的私有化部署极狐GitLab 实例来获取更高的 GitHub API 速率限制。

GitHub API 请求的通常速率限制为每小时 5,000 个请求。使用如下的步骤，您可以获取的每小时 15,000 个请求的速率限制，结果就是导入速度更快。

先决条件：

• 您要有访问 GitHub Enterprise Cloud 组织的权限。
• 极狐GitLab 启用了 GitHub OAuth 配置。

要启用更高的速率限制：

• 在 GitHub 上创建 OAuth app。确保 OAuth app 是所属于 GitHub Enterprise Cloud 组织，而不是您个人 GitHub 账户。
• 使用 GitHub OAuth 执行项目导入。
• 可选。默认情况下，所有配置的 OAuth 提供者都启用了登录。如果您想为导入启用 GitHub OAuth，但是您想组织用户使用 GitHub 登录到您的极狐GitLab 示例，您可以使用 GitHub 禁用登录。

导入的数据

项目的如下条目会被导入：

• 仓库描述。
• Git 仓库数据。
• 所有的项目分支。
• fork 项目上的所有分支，以及与其关联的开除开放状态的拉取请求，并不包括关闭的拉取请求。fork 项目上的分支以 GH-SHA-username/pull-request-number/fork-name/branch 格式被导入。
• 分支保护规则。引入于极狐GitLab 15.4。
• 协作者（成员）。引入于极狐GitLab 15.10。从极狐GitLab 16.0，可以被作为额外的条目进行导入。
• 议题。
• 拉取请求。
• Wiki 页面。
• 里程碑。
• 标签。
• 版本注释内容。
• 以下内容中的附件：
  • 版本注释。引入于极狐GitLab 15.4。
  • 评论。引入于极狐GitLab 15.5。
  • 议题描述。引入于极狐GitLab 15.5。
  • 拉取请求描述。引入于极狐GitLab 15.5。

  导入的所有附件默认禁用，受控于 github_importer_attachments_import 功能标志。从极狐GitLab 15.5 开始，可以作为额外的条目进行导入。功能标志被移除。

• 拉取请求审核意见。
• 常规议题和拉取请求评论。
• Git 大文件存储 (LFS) 对象。
• 拉取请求审核。
• 拉取请求指派的审核者。引入于极狐GitLab 15.6。
• 拉取请求的 被合并 信息。
• 在讨论中的拉取请求评论回复。引入于极狐GitLab 14.5。
• 拉取请求审核评论建议。引入于极狐GitLab 14.7。
• 议题事件和拉取请求事件。引入于极狐GitLab 15.4，并使用名为 github_importer_issue_events_import 的功能标志，默认禁用。从极狐GitLab 15.5 开始，可以作为额外的条目进行导入。功能标志被移除。

指向拉取请求和议题的引用被保留。每个导入的仓库都包含可见性，除非可见性被严格限制。

分支保护规则和项目设置

当这些内容被导入时，支持的 GitHub 分支保护规则会被映射为：

• 极狐GitLab 分支保护规则。
• 项目维度的极狐GitLab 设置。

协作者（成员）

• 引入于极狐GitLab 15.10。

以下的 GitHub 协作者角色会被映射到极狐GitLab 成员角色：

GitHub Enterprise Cloud 有自定义仓库角色功能。极狐GitLab 并不支持这些角色并且会导致部分导入成功。

要导入 GitHub 协作者，您必须至少需要有 GitHub 项目的写角色。否则，协作者导入会被跳过。

在内部网络的 GitHub Enterprise 导入

如果您的 GitHub Enterprise 实例在无法访问互联网的内部网络上，您可以使用反向代理来允许 JihuLab.com 来访问该实例。

代理需要：

• 将请求转发到 GitHub Enterprise 实例。
• 在以下内容中将内部主机名称转化成公共的代理主机名：
  • API 响应体。
  • API 响应的 Link 标头中。

GitHub API 使用 Link 标头来分页。

配置代理后，通过 API 请求来测试。以下是测试 API 的一些示例命令：

curl --header "Authorization: Bearer <YOUR-TOKEN>" "https://{PROXY_HOSTNAME}/user"

### URLs in the response body should use the proxy hostname

{
  "login": "example_username",
  "id": 1,
  "url": "https://{PROXY_HOSTNAME}/users/example_username",
  "html_url": "https://{PROXY_HOSTNAME}/example_username",
  "followers_url": "https://{PROXY_HOSTNAME}/api/v3/users/example_username/followers",
  ...
  "created_at": "2014-02-11T17:03:25Z",
  "updated_at": "2022-10-18T14:36:27Z"
}

curl --head --header "Authorization: Bearer <YOUR-TOKEN>" "https://{PROXY_DOMAIN}/api/v3/repos/{repository_path}/pulls?states=all&sort=created&direction=asc"

### Link header should use the proxy hostname

HTTP/1.1 200 OK
Date: Tue, 18 Oct 2022 21:42:55 GMT
Server: GitHub.com
Content-Type: application/json; charset=utf-8
Cache-Control: private, max-age=60, s-maxage=60
...
X-OAuth-Scopes: repo
X-Accepted-OAuth-Scopes:
github-authentication-token-expiration: 2022-11-22 18:13:46 UTC
X-GitHub-Media-Type: github.v3; format=json
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4997
X-RateLimit-Reset: 1666132381
X-RateLimit-Used: 3
X-RateLimit-Resource: core
Link: <https://{PROXY_DOMAIN}/api/v3/repositories/1/pulls?page=2>; rel="next", <https://{PROXY_DOMAIN}/api/v3/repositories/1/pulls?page=11>; rel="last"

同时也测试一下使用代理克隆仓库不会发生失败：

git clone -c http.extraHeader="Authorization: basic <base64 encode YOUR-TOKEN>" --mirror https://{PROXY_DOMAIN}/{REPOSITORY_PATH}.git

反向代理配置示例

以下是一个如何将 Apache HTTP Server 配置为反向代理的配置示例。

# Required modules
LoadModule filter_module lib/httpd/modules/mod_filter.so
LoadModule reflector_module lib/httpd/modules/mod_reflector.so
LoadModule substitute_module lib/httpd/modules/mod_substitute.so
LoadModule deflate_module lib/httpd/modules/mod_deflate.so
LoadModule headers_module lib/httpd/modules/mod_headers.so
LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_connect_module lib/httpd/modules/mod_proxy_connect.so
LoadModule proxy_http_module lib/httpd/modules/mod_proxy_http.so
LoadModule ssl_module lib/httpd/modules/mod_ssl.so

<VirtualHost GITHUB_ENTERPRISE_HOSTNAME:80>
  ServerName GITHUB_ENTERPRISE_HOSTNAME

  # Enables reverse-proxy configuration with SSL support
  SSLProxyEngine On
  ProxyPass "/" "https://GITHUB_ENTERPRISE_HOSTNAME/"
  ProxyPassReverse "/" "https://GITHUB_ENTERPRISE_HOSTNAME/"

  # Replaces occurrences of the local GitHub Enterprise URL with the Proxy URL
  # GitHub Enterprise compresses the responses, the filters INFLATE and DEFLATE needs to be used to
  # decompress and compress the response back
  AddOutputFilterByType INFLATE;SUBSTITUTE;DEFLATE application/json
  Substitute "s|https://GITHUB_ENTERPRISE_HOSTNAME|https://PROXY_HOSTNAME|ni"
  SubstituteMaxLineLength 50M

  # GitHub API uses the response header "Link" for the API pagination
  # For example:
  #   <https://example.com/api/v3/repositories/1/issues?page=2>; rel="next", <https://example.com/api/v3/repositories/1/issues?page=3>; rel="last"
  # The directive below replaces all occurrences of the GitHub Enterprise URL with the Proxy URL if the
  # response header Link is present
  Header edit* Link "https://GITHUB_ENTERPRISE_HOSTNAME" "https://PROXY_HOSTNAME"
</VirtualHost>

极狐GitLab 技术支持

如果您在迁移过程中遇到任何问题，您可以在极狐GitLab 官方论坛上发帖求助，您也可以直接扫描下方二维码咨询专业人员：