Project remote mirrors API all tiers
Push mirrors defined on a project’s repository settings are called “remote mirrors”. You can query and modify the state of these mirrors with the remote mirror API.
For security reasons, the url
attribute in the API response is always scrubbed of username
and password information.
List a project’s remote mirrors
Returns an array of remote mirrors and their statuses:
GET /projects/:id/remote_mirrors
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors"
Example response:
[
{
"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"
}
]
Get a single project’s remote mirror
Introduced in GitLab 14.10.
Returns a remote mirror and its statuses:
GET /projects/:id/remote_mirrors/:mirror_id
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"
Example response:
{
"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"
}
Create a pull mirror
Learn how to configure a pull mirror using the Projects API.
Create a push mirror
Field mirror_branch_regex
introduced in GitLab 15.8 with a flag named mirror_only_branches_match_regex
. Disabled by default.
mirror_branch_regex
is not available.
To make it available, ask an administrator to enable the feature flag
named mirror_only_branches_match_regex
.
On GitLab.com, this feature is not available.Push mirroring is disabled by default. To enable it, include the optional parameter
enabled
when you create the mirror:
POST /projects/:id/remote_mirrors
Example request:
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"
Example response:
{
"enabled": false,
"id": 101486,
"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"
}
Update a remote mirror’s attributes
mirror_branch_regex
is not available.
To make it available, ask an administrator to enable the feature flag
named mirror_only_branches_match_regex
.
On GitLab.com, this feature is not available.Toggle a remote mirror on or off, or change which types of branches are mirrored:
PUT /projects/:id/remote_mirrors/:mirror_id
Example request:
curl --request PUT --data "enabled=false" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"
Example response:
{
"enabled": false,
"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"
}
Delete a remote mirror
Introduced in GitLab 14.10.
Delete a remote mirror.
DELETE /projects/:id/remote_mirrors/:mirror_id
Attribute | Type | Required | Description |
---|---|---|---|
mirror_id |
Integer | yes | Remote mirror ID. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"