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 来查询和修改这些镜像的状态。

出于安全考虑，API 响应中的 url 属性总是会过滤掉用户名和密码信息。

拉取镜像 使用 不同的 API 端点 来 显示和更新它们。

列出项目的远程镜像

返回远程镜像及其状态的数组：

GET /projects/:id/remote_mirrors

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors"

示例响应：

[
  {
    "enabled": true,
    "id": 101486,
    "auth_method": "ssh_public_key",
    "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",
    "only_protected_branches": true,
    "keep_divergent_refs": true,
    "update_status": "finished",
    "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
  }
]

获取单个项目的远程镜像

返回远程镜像及其状态：

GET /projects/:id/remote_mirrors/:mirror_id

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"

示例响应：

{
  "enabled": true,
  "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",
  "only_protected_branches": true,
  "keep_divergent_refs": true,
  "update_status": "finished",
  "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}

获取单个项目的远程镜像公钥

获取使用 SSH 认证的远程镜像的公钥。

GET /projects/:id/remote_mirrors/:mirror_id/public_key

支持的属性：

属性 类型 必需 描述
id integer/string 是 顶级组的 ID 或 URL 编码路径。
mirror_id integer 是 远程镜像 ID。

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

属性 类型 描述
public_key string 远程镜像的公钥。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486/public_key"

示例响应：

{
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EA..."
}

创建拉取镜像

通过使用项目拉取镜像 API 了解如何 配置拉取镜像。

创建推送镜像

推送镜像默认是禁用的。要启用它，在创建镜像时包含可选参数 enabled：

POST /projects/:id/remote_mirrors
属性 类型 必需 描述
url String 是 仓库镜像的目标 URL。
enabled Boolean 否 确定镜像是否启用。
keep_divergent_refs Boolean 否 确定是否跳过 divergent refs。
only_protected_branches Boolean 否 确定是否只镜像受保护的分支。
mirror_branch_regex String 否 包含正则表达式。只镜像名称与正则表达式匹配的分支。需要禁用 only_protected_branches。仅限 Premium 和 Ultimate。
auth_method String 否 确定镜像认证方法（ssh_public_key 或 password）。

示例请求：

curl --request POST \
  --data "url=https://username:token@example.com/gitlab/example.git" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors"

示例响应：

{
    "enabled": false,
    "id": 101486,
    "auth_method": "password",
    "last_error": null,
    "last_successful_update_at": null,
    "last_update_at": null,
    "last_update_started_at": null,
    "only_protected_branches": false,
    "keep_divergent_refs": false,
    "update_status": "none",
    "url": "https://*****:*****@example.com/gitlab/example.git"
}

更新远程镜像的属性

切换远程镜像的开关状态，或更改镜像的分支类型：

PUT /projects/:id/remote_mirrors/:mirror_id
属性 类型 必需 描述
mirror_id Integer 是 远程镜像 ID。
enabled Boolean 否 确定镜像是否启用。
keep_divergent_refs Boolean 否 确定是否跳过 divergent refs。
only_protected_branches Boolean 否 确定是否只镜像受保护的分支。
mirror_branch_regex String 否 确定是否只镜像名称与正则表达式匹配的分支。与启用的 only_protected_branches 不兼容。仅限 Premium 和 Ultimate。
auth_method String 否 确定镜像认证方法（ssh_public_key 或 password）。

示例请求：

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

示例响应：

{
    "enabled": false,
    "id": 101486,
    "auth_method": "password",
    "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",
    "only_protected_branches": true,
    "keep_divergent_refs": true,
    "update_status": "finished",
    "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}

强制推送镜像更新

强制更新 推送镜像。

POST /projects/:id/remote_mirrors/:mirror_id/sync

支持的属性：

属性 类型 必需 描述
id integer or string 是 项目的 ID 或 URL 编码路径。
mirror_id Integer 是 远程镜像 ID。

如果成功，返回 204。

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486/sync"

示例响应：

HTTP 响应代码 204 的空响应。

删除远程镜像

删除远程镜像。

DELETE /projects/:id/remote_mirrors/:mirror_id
属性 类型 必需 描述
mirror_id Integer 是 远程镜像 ID。

示例请求：

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"