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

Get an array of remote mirrors and their statuses for a project.

GET /projects/:id/remote_mirrors

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`auth_method`	string	Authentication method used for the mirror.
`enabled`	boolean	If `true`, the mirror is enabled.
`host_keys`	array	Array of SSH host key fingerprints for the remote mirror.
`id`	integer	ID of the remote mirror.
`keep_divergent_refs`	boolean	If `true`, divergent refs are kept when mirroring.
`last_error`	string	Error message from the last mirror attempt. `null` if successful.
`last_successful_update_at`	string	Timestamp of the last successful mirror update. ISO 8601 format.
`last_update_at`	string	Timestamp of the last mirror attempt. ISO 8601 format.
`last_update_started_at`	string	Timestamp when the last mirror attempt started. ISO 8601 format.
`only_protected_branches`	boolean	If `true`, only protected branches are mirrored.
`update_status`	string	Status of the mirror update. Possible values: `none`, `scheduled`, `started`, `finished`, `failed`.
`url`	string	Mirror URL with credentials scrubbed for security.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
    "host_keys": [
      {
        "fingerprint_sha256": "SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw"
      }
    ]
  }
]

Get a single project’s remote mirror

Get a single remote mirror and its status for a project.

GET /projects/:id/remote_mirrors/:mirror_id

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`mirror_id`	integer	Yes	ID of the remote mirror.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`enabled`	boolean	If `true`, the mirror is enabled.
`id`	integer	ID of the remote mirror.
`host_keys`	array	Array of SSH host key fingerprints for the remote mirror.
`keep_divergent_refs`	boolean	If `true`, divergent refs are kept when mirroring.
`last_error`	string	Error message from the last mirror attempt. `null` if successful.
`last_successful_update_at`	string	Timestamp of the last successful mirror update. ISO 8601 format.
`last_update_at`	string	Timestamp of the last mirror attempt. ISO 8601 format.
`last_update_started_at`	string	Timestamp when the last mirror attempt started. ISO 8601 format.
`only_protected_branches`	boolean	If `true`, only protected branches are mirrored.
`update_status`	string	Status of the mirror update. Possible values: `none`, `scheduled`, `started`, `finished`, `failed`.
`url`	string	Mirror URL with credentials scrubbed for security.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
  "host_keys": [
    {
      "fingerprint_sha256": "SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw"
    }
  ]
}

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 or string	Yes	ID or URL-encoded path of the project.
`mirror_id`	integer	Yes	ID of the remote mirror.

If successful, returns 200 OK 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

Create a push mirror for a project. Push mirroring is disabled by default. To enable it, include the optional parameter enabled when you create the mirror.

POST /projects/:id/remote_mirrors

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`url`	string	Yes	Target URL to which the repository is mirrored.
`auth_method`	string	No	Mirror authentication method. Accepted values: `ssh_public_key`, `password`.
`enabled`	boolean	No	If `true`, the mirror is enabled.
`keep_divergent_refs`	boolean	No	If `true`, divergent refs are kept when mirroring.
`mirror_branch_regex`	string	No	Regular expression for branch names to mirror. Only branches with names matching the regex are mirrored. Requires `only_protected_branches` to be disabled. Premium and Ultimate only.
`only_protected_branches`	boolean	No	If `true`, only protected branches are mirrored.

If successful, returns 201 Created and the following response attributes:

Attribute	Type	Description
`auth_method`	string	Authentication method used for the mirror.
`enabled`	boolean	If `true`, the mirror is enabled.
`host_keys`	array	Array of SSH host key fingerprints for the remote mirror.
`id`	integer	ID of the remote mirror.
`keep_divergent_refs`	boolean	If `true`, divergent refs are kept when mirroring.
`last_error`	string	Error message from the last mirror attempt. `null` if successful.
`last_successful_update_at`	string	Timestamp of the last successful mirror update. ISO 8601 format.
`last_update_at`	string	Timestamp of the last mirror attempt. ISO 8601 format.
`last_update_started_at`	string	Timestamp when the last mirror attempt started. ISO 8601 format.
`only_protected_branches`	boolean	If `true`, only protected branches are mirrored.
`update_status`	string	Status of the mirror update. Possible values: `none`, `scheduled`, `started`, `finished`, `failed`.
`url`	string	Mirror URL with credentials scrubbed for security.

Example request:

curl --request POST \
  --data "url=https://username:token@example.com/gitlab/example.git" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
    "host_keys": [
      {
        "fingerprint_sha256": "SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw"
      }
    ]
}

Update a remote mirror’s attributes

Update a remote mirror’s configuration. Toggle a remote mirror on or off, or change which types of branches are mirrored.

PUT /projects/:id/remote_mirrors/:mirror_id

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`mirror_id`	integer	Yes	ID of the remote mirror.
`auth_method`	string	No	Mirror authentication method. Accepted values: `ssh_public_key`, `password`.
`enabled`	boolean	No	If `true`, the mirror is enabled.
`keep_divergent_refs`	boolean	No	If `true`, divergent refs are kept when mirroring.
`mirror_branch_regex`	string	No	Regular expression for branch names to mirror. Only branches with names matching the regex are mirrored. Does not work with `only_protected_branches` enabled. Premium and Ultimate only.
`only_protected_branches`	boolean	No	If `true`, only protected branches are mirrored.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`auth_method`	string	Authentication method used for the mirror.
`enabled`	boolean	If `true`, the mirror is enabled.
`host_keys`	array	Array of SSH host key fingerprints for the remote mirror.
`id`	integer	ID of the remote mirror.
`keep_divergent_refs`	boolean	If `true`, divergent refs are kept when mirroring.
`last_error`	string	Error message from the last mirror attempt. `null` if successful.
`last_successful_update_at`	string	Timestamp of the last successful mirror update. ISO 8601 format.
`last_update_at`	string	Timestamp of the last mirror attempt. ISO 8601 format.
`last_update_started_at`	string	Timestamp when the last mirror attempt started. ISO 8601 format.
`only_protected_branches`	boolean	If `true`, only protected branches are mirrored.
`update_status`	string	Status of the mirror update. Possible values: `none`, `scheduled`, `started`, `finished`, `failed`.
`url`	string	Mirror URL with credentials scrubbed for security.

Example request:

curl --request PUT \
  --data "enabled=false" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
    "host_keys": [
      {
        "fingerprint_sha256": "SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw"
      }
    ]
}

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	ID or URL-encoded path of the project.
`mirror_id`	integer	Yes	ID of the remote mirror.

If successful, returns 204 No Content.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486/sync"

Delete a remote mirror

Delete a remote mirror.

DELETE /projects/:id/remote_mirrors/:mirror_id

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`mirror_id`	integer	Yes	ID of the remote mirror.

If successful, returns 204 No Content.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"