Help us learn about your current experience with the documentation. Take the survey.

导入 API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用导入 API 从 GitHub 或 Bitbucket Server 导入仓库。

当您将项目导入到个人命名空间时，不支持用户贡献映射。当您导入到个人命名空间时，所有贡献都会被分配给一个名为 Import User 的非功能性用户，并且无法重新分配。议题 525342 提议将所有贡献映射给执行导入的用户。

从 GitHub 导入仓库

在 GitLab 15.8 中引入，如果 target_namespace 中指定的命名空间或组不存在，GitLab 不再自动创建它们。如果命名空间或组名已被占用或 target_namespace 为空，GitLab 也不再回退到使用用户的个人命名空间。
在 GitLab 16.0 中引入了维护者（Maintainer）角色而非开发者（Developer）角色的要求，并已向后移植到 GitLab 15.11.1 和 GitLab 15.10.5。
optional_stages 中的 collaborators_import 键在 GitLab 16.0 中引入。
功能标志 github_import_extended_events 在 GitLab 16.8 中引入。默认禁用。此标志提高了导入性能，但会禁用 single_endpoint_issue_events_import 可选阶段。
在 GitLab 16.9 中，功能标志 github_import_extended_events 已在 GitLab.com 和 GitLab 自管版上启用。
改进的导入性能在 GitLab 16.11 中正式发布。功能标志 github_import_extended_events 已被移除。

使用 API 将您的项目从 GitHub 导入到 GitLab。

前提条件：

GitHub 导入器的前提条件。
在 target_namespace 中设置的命名空间必须存在。
该命名空间可以是您的用户命名空间，或者您至少拥有维护者（Maintainer）角色的现有组。

POST /import/github

Attribute	Type	Required	Description
`personal_access_token`	string	yes	GitHub 个人访问令牌
`repo_id`	integer	yes	GitHub 仓库 ID
`new_name`	string	no	新项目的名称。也用作新路径，因此不能以特殊字符开头或结尾，并且不能包含连续的特殊字符。
`target_namespace`	string	yes	要将仓库导入到的命名空间。支持像 `/namespace/subgroup` 这样的子组。在 GitLab 15.8 及更高版本中，不能为空
`github_hostname`	string	no	自定义 GitHub Enterprise 主机名。对于 GitHub.com 请勿设置。从 GitLab 16.5 到 GitLab 17.1，您必须包含路径 `/api/v3`。
`optional_stages`	object	no	要导入的其他项目。在 GitLab 15.5 中引入
`timeout_strategy`	string	no	处理导入超时的策略。有效值为 `optimistic`（继续到导入的下一阶段）或 `pessimistic`（立即失败）。默认为 `pessimistic`。在 GitLab 16.5 中引入。
`pagination_limit`	integer	no	每次向 GitHub 发出的 API 请求所检索的项目数量。默认值为每页 100 个项目。对于从大型仓库导入项目，将此数值降低可以减少 GitHub API 端点返回 `500` 或 `502` 错误的风险。但是，减小页面大小会导致迁移时间更长。

curl --request POST \
  --url "https://gitlab.example.com/api/v4/import/github" \
  --header "content-type: application/json" \
  --header "Authorization: Bearer <your_access_token>" \
  --data '{
    "personal_access_token": "aBc123abC12aBc123abC12abC123+_A/c123",
    "repo_id": "12345",
    "target_namespace": "group/subgroup",
    "new_name": "NEW-NAME",
    "github_hostname": "https://github.example.com",
    "optional_stages": {
      "single_endpoint_notes_import": true,
      "attachments_import": true,
      "collaborators_import": true
    }
}'

optional_stages 支持以下键：

single_endpoint_issue_events_import，用于导入议题和拉取请求事件。此可选阶段已在 GitLab 16.9 中移除。
single_endpoint_notes_import，用于替代性的、更彻底的评论导入。
attachments_import，用于导入 Markdown 附件。
collaborators_import，用于导入非外部协作者的直接仓库协作者。

更多信息，请参阅选择要导入的其他项目。

示例响应：

{
    "id": 27,
    "name": "my-repo",
    "full_path": "/root/my-repo",
    "full_name": "Administrator / my-repo",
    "refs_url": "/root/my-repo/refs",
    "import_source": "my-github/repo",
    "import_status": "scheduled",
    "human_import_status_name": "scheduled",
    "provider_link": "/my-github/repo",
    "relation_type": null,
    "import_warning": null
}

使用组访问令牌通过 API 导入公共项目

当您使用组访问令牌通过 API 将项目从 GitHub 导入到 GitLab 时：

GitLab 项目会继承原始项目的可见性设置。因此，如果原始项目是公共的，则该项目也将公开可访问。
如果 path 或 target_namespace 不存在，项目导入将失败。

取消 GitHub 项目导入

使用 API 取消正在进行的 GitHub 项目导入。

POST /import/github/cancel

Attribute	Type	Required	Description
`project_id`	integer	yes	GitLab 项目 ID

curl --request POST \
  --url "https://gitlab.example.com/api/v4/import/github/cancel" \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data '{
    "project_id": 12345
}'

示例响应：

{
    "id": 160,
    "name": "my-repo",
    "full_path": "/root/my-repo",
    "full_name": "Administrator / my-repo",
    "import_source": "source/source-repo",
    "import_status": "canceled",
    "human_import_status_name": "canceled",
    "provider_link": "/source/source-repo"
}

返回以下状态码：

200 OK：项目导入正在被取消。
400 Bad Request：项目导入无法被取消。
404 Not Found：与 project_id 关联的项目不存在。

将 GitHub Gist 导入到 GitLab 代码片段

您可以使用 GitLab API 将个人 GitHub Gist（最多包含 10 个文件）导入到个人 GitLab 代码片段中。包含超过 10 个文件的 GitHub Gist 将被跳过。您应该手动迁移这些 GitHub Gist。

如果有任何 Gist 无法导入，系统会发送一封电子邮件，其中包含未导入的 Gist 列表。

POST /import/github/gists

Attribute	Type	Required	Description
`personal_access_token`	string	yes	GitHub 个人访问令牌

curl --request POST \
  --url "https://gitlab.example.com/api/v4/import/github/gists" \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_gitlab_access_token>" \
  --data '{
    "personal_access_token": "<your_github_personal_access_token>"
}'

返回以下状态码：

202 Accepted：Gist 导入已启动。
401 Unauthorized：用户的 GitHub 个人访问令牌无效。
422 Unprocessable Entity：Gist 导入已在进行中。
429 Too Many Requests：用户已超出 GitHub 的速率限制。

从 Bitbucket Server 导入仓库

使用 API 将您的项目从 Bitbucket Server 导入到 GitLab。

Bitbucket 项目密钥仅用于在 Bitbucket 中查找仓库。如果要将仓库导入到 GitLab 组，则必须指定 target_namespace。如果未指定 target_namespace，项目将导入到您的个人用户命名空间。

前提条件：

更多信息，请参阅 Bitbucket Server 导入器的前提条件。

POST /import/bitbucket_server

Attribute	Type	Required	Description
`bitbucket_server_url`	string	yes	Bitbucket Server URL
`bitbucket_server_username`	string	yes	Bitbucket Server 用户名
`personal_access_token`	string	yes	Bitbucket Server 个人访问令牌/密码
`bitbucket_server_project`	string	yes	Bitbucket 项目密钥
`bitbucket_server_repo`	string	yes	Bitbucket 仓库名称
`new_name`	string	no	新项目的名称。也用作新路径，因此不能以特殊字符开头或结尾，并且不能包含连续的特殊字符。在 GitLab 15.1 到 16.9 之间，项目路径是从 Bitbucket 复制的。在 GitLab 16.10 中，该行为已改回原始行为。
`target_namespace`	string	no	要将仓库导入到的命名空间。支持像 `/namespace/subgroup` 这样的子组
`timeout_strategy`	string	no	处理导入超时的策略。有效值为 `optimistic`（继续到导入的下一阶段）或 `pessimistic`（立即失败）。默认为 `pessimistic`。在 GitLab 16.5 中引入。

curl --request POST \
  --url "https://gitlab.example.com/api/v4/import/bitbucket_server" \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data '{
    "bitbucket_server_url": "http://bitbucket.example.com",
    "bitbucket_server_username": "root",
    "personal_access_token": "Nzk4MDcxODY4MDAyOiP8y410zF3tGAyLnHRv/E0+3xYs",
    "bitbucket_server_project": "NEW",
    "bitbucket_server_repo": "my-repo",
    "new_name": "NEW-NAME"
}'

从 Bitbucket Cloud 导入仓库

使用 API 将您的项目从 Bitbucket Cloud 导入到 GitLab。

前提条件：

Bitbucket Cloud 导入器的前提条件。
一个 Bitbucket Cloud 应用密码。

POST /import/bitbucket

Attribute	Type	Required	Description
`bitbucket_username`	string	yes	Bitbucket Cloud 用户名
`bitbucket_app_password`	string	yes	Bitbucket Cloud 应用密码
`repo_path`	string	yes	仓库的路径
`target_namespace`	string	yes	要将仓库导入到的命名空间。支持像 `/namespace/subgroup` 这样的子组
`new_name`	string	no	新项目的名称。也用作新路径，因此不能以特殊字符开头或结尾，并且不能包含连续的特殊字符。

curl --request POST \
  --url "https://gitlab.example.com/api/v4/import/bitbucket" \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data '{
    "bitbucket_username": "bitbucket_username",
    "bitbucket_app_password": "bitbucket_app_password",
    "repo_path": "username/my_project",
    "target_namespace": "my_group/my_subgroup",
    "new_name": "new_project_name"
}'

导入 API

从 GitHub 导入仓库

使用组访问令牌通过 API 导入公共项目

取消 GitHub 项目导入

将 GitHub Gist 导入到 GitLab 代码片段

从 Bitbucket Server 导入仓库

从 Bitbucket Cloud 导入仓库

相关主题