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

History

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

History

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

History

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

History

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

Project remote mirrors API

List a project’s remote mirrors

Get a single project’s remote mirror

Get a single project’s remote mirror public key

Create a pull mirror

Create a push mirror

Update a remote mirror’s attributes

Force push mirror update

Delete a remote mirror

Help & feedback

Docs

Product

Feature availability and product trials

Get help