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

History

Return the details of a project’s pull mirror.

GET /projects/:id/mirror/pull

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe 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:

AttributeTypeDescription
idintegerThe unique identifier of the mirror configuration.
last_errorstring or nullThe most recent error message, if any. null if no errors occurred.
last_successful_update_atstringTimestamp of the last successful mirror update.
last_update_atstringTimestamp of the most recent mirror update attempt.
last_update_started_atstringTimestamp when the last mirror update process started.
update_statusstringThe status of the mirror update process.
urlstringURL of the mirrored repository.
enabledbooleanIndicates whether the mirror is active or inactive.
mirror_trigger_buildsbooleanDetermines if builds should be triggered for mirror updates.
only_mirror_protected_branchesboolean or nullSpecifies if only protected branches should be mirrored. null if not set.
mirror_overwrites_diverged_branchesbooleanIndicates if diverged branches should be overwritten during mirroring.
mirror_branch_regexstring or nullRegex 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

History

Configure pull mirroring settings.

Supported attributes:

AttributeTypeRequiredDescription
enabledbooleanNoEnables pull mirroring on project when set to true.
urlstringNoURL of remote repository being mirrored.
auth_userstringNoUsername used for authentication of a project to pull mirror.
auth_passwordstringNoPassword used for authentication of a project to pull mirror.
mirror_trigger_buildsbooleanNoTrigger pipelines for mirror updates when set to true.
only_mirror_protected_branchesbooleanNoLimits mirroring to only protected branches when set to true.
mirror_overwrites_diverged_branchesbooleanNoOverwrite diverged branches.
mirror_branch_regexStringNoContains 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)

History

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:

AttributeTypeRequiredDescription
import_urlstringYesURL of remote repository being mirrored (with user:token if needed).
mirrorbooleanYesEnables pull mirroring on project when set to true.
mirror_trigger_buildsbooleanNoTrigger pipelines for mirror updates when set to true.
only_mirror_protected_branchesbooleanNoLimits mirroring to only protected branches when set to true.
mirror_branch_regexStringNoContains 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:

AttributeTypeRequiredDescription
idinteger or stringYesThe 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"