Project remote mirrors API (FREE)

Push mirrors 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

Introduced in GitLab 12.9.

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"
  }
]

NOTE: For security reasons, the url attribute is always scrubbed of username and password information.

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"
}

NOTE: For security reasons, the url attribute is always scrubbed of username and password information.

Create a pull mirror

Learn how to configure a pull mirror using the Projects API.

Create a push mirror

Introduced in GitLab 12.9.

Push mirroring is disabled by default. You can enable it by including the optional parameter enabled when creating it:

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.
`only_protected_branches`	Boolean	no	Determines if only protected branches are mirrored.
`keep_divergent_refs`	Boolean	no	Determines if divergent refs are skipped.

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

Introduced in GitLab 12.9.

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.
`only_protected_branches`	Boolean	no	Determines if only protected branches are mirrored.
`keep_divergent_refs`	Boolean	no	Determines if divergent refs are skipped.

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"