Project remote mirrors API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
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.
Pull mirrors use a different API endpoint to display and update them.
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,
"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 a single project’s remote mirror
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"
}
Get a single project’s remote mirror public key
Get the public key of a remote mirror that uses SSH authentication.
GET /projects/:id/remote_mirrors/:mirror_id/public_key
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer/string | Yes | ID or URL-encoded path of a top-level group. |
mirror_id | integer | Yes | Remote mirror ID. |
If successful, returns 200
and the following
response attributes:
Attribute | Type | Description |
---|---|---|
public_key | string | Public key of the remote mirror. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486/public_key"
Example response:
{
"public_key": "ssh-rsa AAAAB3NzaC1yc2EA..."
}
Create a pull mirror
Learn how to configure a pull mirror by using the project pull mirroring API.
Create a push mirror
Push mirroring is disabled by default. To enable it, include the optional parameter
enabled
when you create the mirror:
POST /projects/:id/remote_mirrors
Attribute | Type | Required | Description |
---|---|---|---|
url | String | yes | The target URL to which the repository is mirrored. |
enabled | Boolean | no | Determines if the mirror is enabled. |
keep_divergent_refs | Boolean | no | Determines if divergent refs are skipped. |
only_protected_branches | Boolean | no | Determines if only protected branches are mirrored. |
mirror_branch_regex | String | no | Contains a regular expression. Only branches with names matching the regex are mirrored. Requires only_protected_branches to be disabled. Premium and Ultimate only. |
auth_method | String | no | Determines the mirror authentication method (ssh_public_key or password ). |
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,
"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"
}
Update a remote mirror’s attributes
Toggle a remote mirror on or off, or change which types of branches are mirrored:
PUT /projects/:id/remote_mirrors/:mirror_id
Attribute | Type | Required | Description |
---|---|---|---|
mirror_id | Integer | yes | The remote mirror ID. |
enabled | Boolean | no | Determines if the mirror is enabled. |
keep_divergent_refs | Boolean | no | Determines if divergent refs are skipped. |
only_protected_branches | Boolean | no | Determines if only protected branches are mirrored. |
mirror_branch_regex | String | no | Determines if only the branch whose name matches the regex is mirrored. It does not work with only_protected_branches enabled. Premium and Ultimate only. |
auth_method | String | no | Determines the mirror authentication method (ssh_public_key or password ). |
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,
"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"
}
Force push mirror update
Force an update to a push mirror.
POST /projects/:id/remote_mirrors/:mirror_id/sync
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the project. |
mirror_id | Integer | Yes | The remote mirror ID. |
If successful, returns 204
.
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486/sync"
Example response:
An empty response with a HTTP response code 204.
Delete a remote mirror
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"
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support