- Get a project’s pull mirror details
- Configure pull mirroring for a project
- Configure pull mirroring for a project (deprecated)
- Start the pull mirroring process for a project
Pull mirroring API
You can manage project pull mirroring by using the REST API.
Get a project’s pull mirror details
- Introduced in GitLab 15.6.
-
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
, andmirror_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 | The ID or URL-encoded path of the project. |
Example request:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"
If successful, returns 200 OK
and the
following response attributes:
Attribute | Type | Description |
---|---|---|
id
| integer | The unique identifier of the mirror configuration. |
last_error
| string or null | The 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. |
update_status
| string | The status of the mirror update process. |
url
| string | URL of the mirrored repository. |
enabled
| boolean | Indicates whether the mirror is active or inactive. |
mirror_trigger_builds
| boolean | Determines if builds should be triggered for mirror updates. |
only_mirror_protected_branches
| boolean or null | Specifies if only protected branches should be mirrored. null if not set.
|
mirror_overwrites_diverged_branches
| boolean | Indicates if diverged branches should be overwritten during mirroring. |
mirror_branch_regex
| string or null | Regex pattern for filtering which branches to mirror. null if not set.
|
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
- Introduced in GitLab 17.6.
Configure pull mirroring settings.
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
enabled
| boolean | No | Enables pull mirroring on project when set to true .
|
url
| string | No | URL of remote repository being mirrored. |
auth_user
| string | No | Username used for authentication of a project to pull mirror. |
auth_password
| string | No | Password used for authentication of a project to pull mirror. |
mirror_trigger_builds
| boolean | No | Trigger pipelines for mirror updates when set to true .
|
only_mirror_protected_branches
| boolean | No | Limits mirroring to only protected branches 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.
|
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>" \
--url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" \
--data "enabled=false"
Configure pull mirroring for a project (deprecated)
- Field
mirror_branch_regex
introduced in GitLab 15.8 with a flag namedmirror_only_branches_match_regex
. Disabled by default. - 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.
Configure pull mirroring while creating a new project or
updating an existing project by using the API if the remote repository is accessible publicly or by
using username:token
authentication.
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 | Enables pull mirroring on project when set to true .
|
mirror_trigger_builds
| boolean | No | Trigger pipelines for mirror updates when set to true .
|
only_mirror_protected_branches
| boolean | No | Limits mirroring to only protected branches 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.
|
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>" \
--url "https://gitlab.example.com/api/v4/projects/:id" \
--data "mirror=true&import_url=https://username:token@gitlab.example.com/group/project.git"
Example removing pull mirroring:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/:id" \
--data "mirror=false"
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 | The ID or URL-encoded path of the project. |
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"