Text of docs.gitlab.com › api › project_pull_mirroring as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

Pull mirroring API | GitLab Docs

/ Pull mirroring API Tier : Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Use this API to manage project pull mirroring . Retrieve project pull mirror details 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 .

Retrieves pull mirror details for a specified project. 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. Possible values: none , scheduled , started , finished , failed , or canceled . url string URL of the mirrored repository. Example request: shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" Example response: json { "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 } Update project pull mirroring settings Introduced in GitLab 17.6.

Changed in GitLab 19.5. Sending both only_mirror_protected_branches and mirror_branch_regex now returns 400 Bad Request instead of silently forcing only_mirror_protected_branches to false . Updates 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. Omit only_mirror_protected_branches when using this attribute. Sending both returns 400 Bad Request , even when only_mirror_protected_branches is false . 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.

Omit mirror_branch_regex when using this attribute. Sending both returns 400 Bad Request . 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: shell 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: shell 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: json { "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 } Update pull mirroring for a project (deprecated) 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: shell 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: shell 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: shell 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 Introduced the force attribute in GitLab 19.3.

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 . force boolean No If true , resets a hard-failed mirror and retries the update. Ignored for requests authenticated with a GitHub webhook signature. If successful, returns 200 OK . Example request: shell curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" To recover a hard-failed mirror, set force to true .

For more information, see fix hard failures when mirroring . Example request: shell curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data "force=true" \ --url "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" Was this page helpful?