2020-07-30 12:09:33 +00:00
---
stage: Create
group: Source Code
2020-11-26 06:09:20 +00:00
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-07-30 12:09:33 +00:00
type: reference, api
---
2021-02-09 18:09:59 +00:00
# Project remote mirrors API **(FREE)**
2020-03-06 21:07:59 +00:00
2021-09-24 06:12:16 +00:00
[Push mirrors ](../user/project/repository/mirror/push.md )
2020-03-06 21:07:59 +00:00
defined on a project's repository settings are called "remote mirrors", and the
state of these mirrors can be queried and modified via the remote mirror API
outlined below.
## List a project's remote mirrors
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38121) in GitLab 12.9.
2020-03-06 21:07:59 +00:00
Returns an Array of remote mirrors and their statuses:
2020-05-20 03:08:04 +00:00
```plaintext
2020-03-06 21:07:59 +00:00
GET /projects/:id/remote_mirrors
```
Example request:
2020-05-19 18:08:11 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/42/remote_mirrors"
2020-03-06 21:07:59 +00:00
```
Example response:
```json
[
{
"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,
2020-05-19 00:07:58 +00:00
"keep_divergent_refs": true,
2020-03-06 21:07:59 +00:00
"update_status": "finished",
"url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
For security reasons, the `url` attribute is always scrubbed of username
2020-03-06 21:07:59 +00:00
and password information.
2021-10-07 06:09:58 +00:00
## Create a pull mirror
Learn how to [configure a pull mirror ](projects.md#configure-pull-mirroring-for-a-project ) using the Projects API.
## Create a push mirror
2020-03-06 21:07:59 +00:00
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24189) in GitLab 12.9.
2020-03-06 21:07:59 +00:00
2021-10-07 06:09:58 +00:00
Push mirroring is disabled by default. You can enable it by including the optional parameter `enabled` when creating it:
2020-03-06 21:07:59 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2020-03-06 21:07:59 +00:00
POST /projects/:id/remote_mirrors
```
| Attribute | Type | Required | Description |
| :---------- | :----- | :--------- | :------------ |
2021-10-07 06:09:58 +00:00
| `url` | String | yes | The target URL to which the repository is mirrored. |
2020-03-06 21:07:59 +00:00
| `enabled` | Boolean | no | Determines if the mirror is enabled. |
| `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. |
2020-05-19 00:07:58 +00:00
| `keep_divergent_refs` | Boolean | no | Determines if divergent refs are skipped. |
2020-03-06 21:07:59 +00:00
Example request:
2020-05-19 18:08:11 +00:00
```shell
2021-06-02 15:09:59 +00:00
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"
2020-03-06 21:07:59 +00:00
```
Example response:
```json
{
"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,
2020-05-19 00:07:58 +00:00
"keep_divergent_refs": false,
2020-03-06 21:07:59 +00:00
"update_status": "none",
"url": "https://*****:*****@example.com/gitlab/example.git"
}
```
## Update a remote mirror's attributes
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38121) in GitLab 12.9.
2020-03-06 21:07:59 +00:00
Toggle a remote mirror on or off, or change which types of branches are
mirrored:
2020-05-20 03:08:04 +00:00
```plaintext
2020-03-06 21:07:59 +00:00
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. |
| `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. |
2020-05-19 00:07:58 +00:00
| `keep_divergent_refs` | Boolean | no | Determines if divergent refs are skipped. |
2020-03-06 21:07:59 +00:00
Example request:
2020-05-19 18:08:11 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request PUT --data "enabled=false" --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"
2020-03-06 21:07:59 +00:00
```
Example response:
```json
{
"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,
2020-05-19 00:07:58 +00:00
"keep_divergent_refs": true,
2020-03-06 21:07:59 +00:00
"update_status": "finished",
"url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git"
}
```