Pull mirroring API
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
You can manage project pull mirroring by using the REST API.
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 | The ID or URL-encoded path of the project. |
Example request:
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "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
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_overwrites_diverged_branches |
boolean | No | Overwrite diverged branches. |
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)
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.
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>" \
--url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support