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 integerThe ID or URL-encoded path of the project
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OKAPIEntitiesRemoteMirror
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 integerThe ID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
auth_methodStringDetermines the mirror authentication method
Allowed values: ssh_public_key, password
enabledBooleanDetermines if the mirror is enabled
host_keysArray of stringsSSH host keys in bare format (ssh-ed25519 AAAA…) or full known_hosts format (hostname ssh-ed25519 AAAA…). Bare keys use the hostname from the mirror URL
keep_divergent_refsBooleanDetermines if divergent refs are kept on the target
only_protected_branchesBooleanDetermines if only protected branches are mirrored
url
Required		StringThe URL for a remote mirror
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 integerThe ID or URL-encoded path of the project
mirror_id
Path, required		StringThe ID of a 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 integerThe ID or URL-encoded path of the project
mirror_id
Path, required		StringThe ID of a remote mirror

Request body (application/json)

PropertyTypeDescription
auth_methodStringDetermines the mirror authentication method
enabledBooleanDetermines if the mirror is enabled
Example: true
host_keysArray of stringsSSH host keys in bare format (ssh-ed25519 AAAA…) or full known_hosts format (hostname ssh-ed25519 AAAA…). Bare keys use the hostname from the mirror URL
keep_divergent_refsBooleanDetermines if divergent refs are kept on the target
only_protected_branchesBooleanDetermines if 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 integerThe ID or URL-encoded path of the project
mirror_id
Path, required		StringThe ID of a 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 integerThe ID or URL-encoded path of the project
mirror_id
Path, required		StringThe ID of a 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 integerThe ID or URL-encoded path of the project
mirror_id
Path, required		StringThe ID of a 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
→