Pull mirroring API

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use the pull mirroring API to manage a project's pull mirroring.

Get a project's pull mirror details

Version history

Extended response to include mirror configuration information in GitLab 17.5. The following configuration settings are included: enabled, mirror_trigger_builds, only_mirror_protected_branches, mirror_overwrites_diverged_branches, and mirror_branch_regex.

Return the details of a project's pull mirror.

GET /projects/:id/mirror/pull

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
`enabled`	boolean	If `true`, the mirror is active.
`id`	integer	Unique identifier of the mirror configuration.
`last_error`	string or null	Most recent error message, if any. `null` if no errors occurred.
`last_successful_update_at`	string	Timestamp of the last successful mirror update.
`last_update_at`	string	Timestamp of the most recent mirror update attempt.
`last_update_started_at`	string	Timestamp when the last mirror update process started.
`mirror_branch_regex`	string or null	Regex pattern for filtering which branches to mirror. `null` if not set.
`mirror_overwrites_diverged_branches`	boolean	If `true`, overwrites diverged branches during mirroring.
`mirror_trigger_builds`	boolean	If `true`, triggers builds for mirror updates.
`only_mirror_protected_branches`	boolean or null	If `true`, only protected branches are mirrored. If not set, the value is `null`.
`update_status`	string	Status of the mirror update process.
`url`	string	URL of the mirrored repository.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"

Example response:

{
  "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",
  "update_status": "finished",
  "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git",
  "enabled": true,
  "mirror_trigger_builds": true,
  "only_mirror_protected_branches": null,
  "mirror_overwrites_diverged_branches": false,
  "mirror_branch_regex": null
}

Configure pull mirroring for a project

Version history

Introduced in GitLab 17.6.

Configure pull mirroring settings for a project.

PUT /projects/:id/mirror/pull

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`auth_password`	string	No	Password used for authentication of a project to pull mirror.
`auth_user`	string	No	Username used for authentication of a project to pull mirror.
`enabled`	boolean	No	If `true`, enables pull mirroring on project when set to `true`.
`mirror_branch_regex`	string	No	Contains a regular expression. Only branches with names matching the regex are mirrored. Requires `only_mirror_protected_branches` to be disabled.
`mirror_overwrites_diverged_branches`	boolean	No	If `true`, overwrites diverged branches.
`mirror_trigger_builds`	boolean	No	If `true`, triggers pipelines for mirror updates.
`only_mirror_protected_branches`	boolean	No	If `true`, limits mirroring to only protected branches.
`url`	string	No	URL of remote repository being mirrored.

If successful, returns 200 OK and the updated pull mirror configuration.

Example request to add pull mirroring:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "enabled": true,
    "url": "https://gitlab.example.com/group/project.git",
    "auth_user": "user",
    "auth_password": "password"
  }' \
  --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"

Example request to remove pull mirroring:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "enabled=false" \
  --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"

Example response:

{
  "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",
  "update_status": "finished",
  "url": "https://gitlab.example.com/group/project.git",
  "enabled": true,
  "mirror_trigger_builds": false,
  "only_mirror_protected_branches": null,
  "mirror_overwrites_diverged_branches": false,
  "mirror_branch_regex": null
}

Configure pull mirroring for a project (deprecated)

Version history

Feature flag mirror_only_branches_match_regex enabled by default in GitLab 16.0.
Generally available in GitLab 16.2. Feature flag mirror_only_branches_match_regex removed.
Deprecated in GitLab 17.6.

This configuration option was deprecated in GitLab 17.6 and is planned for removal in v5 of the API. Use the new configuration and endpoint instead. This change is a breaking change.

If the remote repository is publicly accessible or uses username:token authentication, use the API to configure pull mirroring when creating or updating a project.

If your HTTP repository is not publicly accessible, you can add the authentication information to the URL. For example, https://username:token@gitlab.company.com/group/project.git where token is a personal access token with the api scope enabled.

Supported attributes:

Attribute	Type	Required	Description
`import_url`	string	Yes	URL of remote repository being mirrored (with `user:token` if needed).
`mirror`	boolean	Yes	If `true`, enables pull mirroring.
`mirror_branch_regex`	string	No	Contains a regular expression. Only branches with names matching the regex are mirrored. Requires `only_mirror_protected_branches` to be disabled.
`mirror_trigger_builds`	boolean	No	If `true`, triggers pipelines for mirror updates.
`only_mirror_protected_branches`	boolean	No	If `true`, limits mirroring to only protected branches.

Example creating a project with pull mirroring:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "new_project",
    "namespace_id": "1",
    "mirror": true,
    "import_url": "https://username:token@gitlab.example.com/group/project.git"
  }' \
  --url "https://gitlab.example.com/api/v4/projects/"

Example adding pull mirroring:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "mirror=true&import_url=https://username:token@gitlab.example.com/group/project.git" \
  --url "https://gitlab.example.com/api/v4/projects/:id"

Example removing pull mirroring:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "mirror=false" \
  --url "https://gitlab.example.com/api/v4/projects/:id"

Start the pull mirroring process for a project

Start the pull mirroring process for a project.

POST /projects/:id/mirror/pull

Supported attributes:

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

If successful, returns 202 Accepted.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"