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:

Copy to clipboard
GET /projects/:id/remote_mirrors

Example request:

Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors"

Example response:

Copy to clipboard
[
  {
    "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:

Copy to clipboard
GET /projects/:id/remote_mirrors/:mirror_id

Example request:

Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486"

Example response:

Copy to clipboard
{
  "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.

Copy to clipboard
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:

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

Example response:

Copy to clipboard
{
  "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:

Copy to clipboard
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:

Copy to clipboard
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:

Copy to clipboard
{
    "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:

Copy to clipboard
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:

Copy to clipboard
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:

Copy to clipboard
{
    "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.

Copy to clipboard
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:

Copy to clipboard
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.

Copy to clipboard
DELETE /projects/:id/remote_mirrors/:mirror_id
Attribute Type Required Description
mirror_id Integer yes Remote mirror ID.

Example request:

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