Use this API to manage remote mirrors. You can query and modify the state of these mirrors.

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 all remote mirrors for a project

GET /api/v4/projects/{id}/remote_mirrors

Lists all remote mirrors for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKArray of APIEntitiesRemoteMirror
400Bad Request—
401Unauthorized—
404Not found—

Create a push mirror

POST /api/v4/projects/{id}/remote_mirrors

Creates a push mirror.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
auth_methodStringMirror authentication method
Allowed values: ssh_public_key, password
enabledBooleanIf true, the mirror is enabled
host_keysArray of stringsSSH host keys in bare format, such as ssh-ed25519 AAAA..., or full known_hosts format, such as hostname ssh-ed25519 AAAA.... Bare keys use the hostname from the mirror URL
keep_divergent_refsBooleanIf true, divergent refs are kept when mirroring
only_protected_branchesBooleanIf true, only protected branches are mirrored
url
Required		StringTarget URL to which the repository is mirrored
Example: https://*****:*****@example.com/gitlab/example.git

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesRemoteMirror
400Bad request—
401Unauthorized—
404Not found—

Retrieve a remote mirror for a project

GET /api/v4/projects/{id}/remote_mirrors/{mirror_id}

Retrieves a specified remote mirror for a project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
mirror_id
Path, required		StringID of the remote mirror

Responses

CodeDescriptionSchema
200OKAPIEntitiesRemoteMirror
400Bad Request—
401Unauthorized—
404Not found—

Update a remote mirror in a project

PUT /api/v4/projects/{id}/remote_mirrors/{mirror_id}

Updates the configuration or operational status of a specified remote mirror.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
mirror_id
Path, required		StringID of the remote mirror

Request body (application/json)

PropertyTypeDescription
auth_methodStringMirror authentication method
enabledBooleanIf true, the mirror is enabled
Example: true
host_keysArray of stringsSSH host keys in bare format, such as ssh-ed25519 AAAA..., or full known_hosts format, such as hostname ssh-ed25519 AAAA.... Bare keys use the hostname from the mirror URL
keep_divergent_refsBooleanIf true, divergent refs are kept when mirroring
only_protected_branchesBooleanIf true, only protected branches are mirrored

Responses

CodeDescriptionSchema
200OKAPIEntitiesRemoteMirror
400Bad request—
401Unauthorized—
404Not found—

Delete a remote mirror from a project

DELETE /api/v4/projects/{id}/remote_mirrors/{mirror_id}

Deletes a specified remote mirror from a project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
mirror_id
Path, required		StringID of the remote mirror

Responses

CodeDescriptionSchema
204No Content—
400Bad request—
401Unauthorized—
404Not found—

Retrieve a public key for a remote mirror

GET /api/v4/projects/{id}/remote_mirrors/{mirror_id}/public_key

Retrieves the public key of a specified remote mirror that uses SSH authentication.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
mirror_id
Path, required		StringID of the remote mirror

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
401Unauthorized—
404Not found—

Force push mirror update

POST /api/v4/projects/{id}/remote_mirrors/{mirror_id}/sync

Forces an update to a push mirror.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
mirror_id
Path, required		StringID of the remote mirror

Responses

CodeDescriptionSchema
204No Content—
400Bad request—
401Unauthorized—
404Not found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesMirrorHostKey

PropertyTypeDescription
fingerprint_sha256StringExample: SHA256:abcd1234

APIEntitiesRemoteMirror

PropertyTypeDescription
auth_methodStringExample: password
enabledBooleanExample: true
host_keysArray of APIEntitiesMirrorHostKey—
idInteger (int64)Example: 101486
keep_divergent_refsBoolean—
last_errorStringExample: The remote mirror URL is invalid.
last_successful_update_atString (date-time)Example: 2020-01-06T17:31:55.864Z
last_update_atString (date-time)Example: 2020-01-06T17:32:02.823Z
last_update_started_atString (date-time)Example: 2020-01-06T17:32:02.823Z
only_protected_branchesBoolean—
update_statusStringExample: finished
urlStringExample: https://*****:*****@example.com/gitlab/example.git
←
REST API / Releases
REST API / Repositories
→