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

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

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)

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"