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

拉取镜像 API

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

使用拉取镜像 API 来管理项目的 拉取镜像。

获取项目的拉取镜像详情

返回项目的 拉取镜像 的详情。

GET /projects/:id/mirror/pull

支持的属性：

属性 类型 必需 描述
id integer or string Yes 项目的 ID 或 URL 编码路径。

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"

如果成功，返回 200 OK 和以下响应属性：

属性 类型 描述
id integer 镜像配置的唯一标识符。
last_error string or null 最近一次的错误消息，如果有。如果没有错误，则为 null。
last_successful_update_at string 上一次成功镜像更新的时间戳。
last_update_at string 最近一次镜像更新尝试的时间戳。
last_update_started_at string 上一次镜像更新进程开始的时间戳。
update_status string 镜像更新进程的状态。
url string 被镜像的仓库的 URL。
enabled boolean 指示镜像是否处于活动或非活动状态。
mirror_trigger_builds boolean 决定是否应为镜像更新触发构建。
only_mirror_protected_branches boolean or null 指定是否只镜像受保护的分支。如果未设置，则为 null。
mirror_overwrites_diverged_branches boolean 指示在镜像过程中是否应覆盖已分叉的分支。
mirror_branch_regex string or null 用于过滤要镜像的分支的正则表达式模式。如果未设置，则为 null。

示例响应：

{
  "id": 101486,
  "last_error": null,
  "last_successful_update_at": "2020-01-06T17:32:02.823Z",
  "last_update_at": "2020-01-06T17:32:02.823Z",
  "last_update_started_at": "2020-01-06T17:31:55.864Z",
  "update_status": "finished",
  "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git",
  "enabled": true,
  "mirror_trigger_builds": true,
  "only_mirror_protected_branches": null,
  "mirror_overwrites_diverged_branches": false,
  "mirror_branch_regex": null
}

为项目配置拉取镜像

配置拉取镜像设置。

支持的属性：

属性 类型 必需 描述
enabled boolean No 设置为 true 时启用项目的拉取镜像。
url string No 被镜像的远程仓库的 URL。
auth_user string No 用于项目拉取镜像认证的用户名。
auth_password string No 用于项目拉取镜像认证的密码。
mirror_trigger_builds boolean No 设置为 true 时为镜像更新触发流水线。
only_mirror_protected_branches boolean No 设置为 true 时限制只镜像受保护的分支。
mirror_overwrites_diverged_branches boolean No 覆盖已分叉的分支。
mirror_branch_regex String No 包含一个正则表达式。只有名称与正则表达式匹配的分支才会被镜像。要求 only_mirror_protected_branches 被禁用。

示例请求添加拉取镜像：

curl --request PUT \
 --header "PRIVATE-TOKEN: <your_access_token>" \
 --header "Content-Type: application/json" \
 --data '{
  "enabled": true,
  "url": "https://gitlab.example.com/group/project.git",
  "auth_user": "user",
  "auth_password": "password"
 }' \
 --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"

示例请求移除拉取镜像：

curl --request PUT \
 --header "PRIVATE-TOKEN: <your_access_token>" \
 --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"  \
 --data "enabled=false"

为项目配置拉取镜像（已弃用）

此配置选项在 GitLab 17.6 中 已弃用 并计划在 API v5 中移除。请改用 新的配置和端点。 此更改是一个破坏性更改。

如果远程仓库是公开可访问的或使用 username:token 认证，请在 创建 或 更新 项目时使用 API 来配置拉取镜像。

如果您的 HTTP 仓库不是公开可访问的，您可以将认证信息添加到 URL 中。例如， https://username:token@gitlab.company.com/group/project.git，其中 token 是一个 个人访问令牌，启用了 api 权限。

支持的属性：

属性 类型 必需 描述
import_url string Yes 被镜像的远程仓库的 URL（如果需要，包含 user:token）。
mirror boolean Yes 设置为 true 时启用项目的拉取镜像。
mirror_trigger_builds boolean No 设置为 true 时为镜像更新触发流水线。
only_mirror_protected_branches boolean No 设置为 true 时限制只镜像受保护的分支。
mirror_branch_regex String No 包含一个正则表达式。只有名称与正则表达式匹配的分支才会被镜像。要求 only_mirror_protected_branches 被禁用。

示例创建带有拉取镜像的项目：

curl --request POST \
 --header "PRIVATE-TOKEN: <your_access_token>" \
 --header "Content-Type: application/json" \
 --data '{
  "name": "new_project",
  "namespace_id": "1",
  "mirror": true,
  "import_url": "https://username:token@gitlab.example.com/group/project.git"
 }' \
 --url "https://gitlab.example.com/api/v4/projects/"

示例添加拉取镜像：

curl --request PUT \
 --header "PRIVATE-TOKEN: <your_access_token>" \
 --url "https://gitlab.example.com/api/v4/projects/:id" \
 --data "mirror=true&import_url=https://username:token@gitlab.example.com/group/project.git"

示例移除拉取镜像：

curl --request PUT \
 --header "PRIVATE-TOKEN: <your_access_token>" \
 --url "https://gitlab.example.com/api/v4/projects/:id"  \
 --data "mirror=false"

启动项目的拉取镜像进程

启动项目的拉取镜像进程。

POST /projects/:id/mirror/pull

支持的属性：

属性 类型 必需 描述
id integer or string Yes 项目的 ID 或 URL 编码路径。

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"