项目远端镜像 API

Tier: 基础版, 专业版, 旗舰版
Offering: JihuLab.com, 私有化部署

推送镜像在项目的仓库设置中定义为远程镜像。您可以使用远程镜像 API 查询和修改这些镜像的状态。

出于安全原因，API 响应中的 url 属性始终会被清除用户名和密码信息。

[拉取镜像](../user/project/repository/mirror/pull.md) 使用 [不同的 API 端点](project_pull_mirroring.md#configure-pull-mirroring-for-a-project) 来显示和更新它们。

列出项目的远程镜像#

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

plaintext
GET /projects/:id/remote_mirrors

示例请求：

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

示例响应：

json
1[
2  {
3    "enabled": true,
4    "id": 101486,
5    "auth_method": "ssh_public_key",
6    "last_error": null,
7    "last_successful_update_at": "2020-01-06T17:32:02.823Z",
8    "last_update_at": "2020-01-06T17:32:02.823Z",
9    "last_update_started_at": "2020-01-06T17:31:55.864Z",
10    "only_protected_branches": true,
11    "keep_divergent_refs": true,
12    "update_status": "finished",
13    "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
14  }
15]

获取单个项目的远程镜像#

返回一个远程镜像及其状态：

plaintext
GET /projects/:id/remote_mirrors/:mirror_id

示例请求：

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

示例响应：

json
1{
2  "enabled": true,
3  "id": 101486,
4  "last_error": null,
5  "last_successful_update_at": "2020-01-06T17:32:02.823Z",
6  "last_update_at": "2020-01-06T17:32:02.823Z",
7  "last_update_started_at": "2020-01-06T17:31:55.864Z",
8  "only_protected_branches": true,
9  "keep_divergent_refs": true,
10  "update_status": "finished",
11  "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
12}

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

History

引入于极狐 GitLab 17.9。

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

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

支持的属性：

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

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

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

示例请求：

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

示例响应：

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

创建拉取镜像#

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

创建推送镜像#

History

字段 mirror_branch_regex 在极狐 GitLab 15.8 中引入，使用名为 mirror_only_branches_match_regex 的功能标志。默认禁用。
在极狐 GitLab 16.0 中默认禁用。
在极狐 GitLab 16.2 中 GA。功能标志 mirror_only_branches_match_regex 被移除。
字段 auth_method 在极狐 GitLab 16.10 中引入。

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

plaintext
POST /projects/:id/remote_mirrors

属性	类型	必需	描述
url	String	是	仓库镜像的目标 URL。
enabled	Boolean	否	确定镜像是否启用。
keep_divergent_refs	Boolean	否	确定是否跳过不同的 refs。
only_protected_branches	Boolean	否	确定是否仅镜像受保护的分支。
mirror_branch_regex	String	否	包含正则表达式。仅镜像名称匹配正则表达式的分支。需要禁用 only_protected_branches。仅专业版和旗舰版。
auth_method	String	否	确定镜像认证方法 (ssh_public_key 或 password)。

示例请求：

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

示例响应：

json
1{
2    "enabled": false,
3    "id": 101486,
4    "auth_method": "password",
5    "last_error": null,
6    "last_successful_update_at": null,
7    "last_update_at": null,
8    "last_update_started_at": null,
9    "only_protected_branches": false,
10    "keep_divergent_refs": false,
11    "update_status": "none",
12    "url": "https://*****:*****@example.com/gitlab/example.git"
13}

更新远程镜像的属性#

History

字段 auth_method 在极狐 GitLab 16.10 中引入。

打开或关闭远程镜像，或更改镜像的分支类型：

plaintext
PUT /projects/:id/remote_mirrors/:mirror_id

属性	类型	必需	描述
mirror_id	Integer	是	远程镜像 ID。
enabled	Boolean	否	确定镜像是否启用。
keep_divergent_refs	Boolean	否	确定是否跳过不同的 refs。
only_protected_branches	Boolean	否	确定是否仅镜像受保护的分支。
mirror_branch_regex	String	否	确定是否仅镜像名称匹配正则表达式的分支。它不与 only_protected_branches 启用一起工作。仅专业版和旗舰版。
auth_method	String	否	确定镜像认证方法 (ssh_public_key 或 password)。

示例请求：

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

示例响应：

json
1{
2    "enabled": false,
3    "id": 101486,
4    "auth_method": "password",
5    "last_error": null,
6    "last_successful_update_at": "2020-01-06T17:32:02.823Z",
7    "last_update_at": "2020-01-06T17:32:02.823Z",
8    "last_update_started_at": "2020-01-06T17:31:55.864Z",
9    "only_protected_branches": true,
10    "keep_divergent_refs": true,
11    "update_status": "finished",
12    "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
13}

强制推送镜像更新#

History

引入于极狐 GitLab 16.11。

强制更新推送镜像。

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

支持的属性：

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

如果成功，则返回 204。

示例请求：

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

示例响应：

一个空响应，HTTP 响应代码 204。

删除远程镜像#

删除远程镜像。

plaintext
DELETE /projects/:id/remote_mirrors/:mirror_id

属性	类型	必需	描述
mirror_id	Integer	是	远程镜像 ID。

示例请求：

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