Project Relations Export API

Introduced in GitLab 14.4 behind the bulk_import feature flag, disabled by default.

On GitLab.com, this feature is available. On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to disable the bulk_import flag. The feature is not ready for production use. It is still in experimental stage and might change in the future.

With the Project Relations Export API, you can partially export project structure. This API is similar to project export, but it exports each top-level relation (for example, milestones/boards/labels) as a separate file instead of one archive. The project relations export API is primarily used in group migration to support group project import.

Schedule new export

Start a new project relations export:

POST /projects/:id/export_relations
Attribute Type Required Description
id integer/string yes ID of the project owned by the authenticated user. 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/export_relations"

{
  "message": "202 Accepted"
}

Export status

View the status of the relations export:

GET /projects/:id/export_relations/status
Attribute Type Required Description
id integer/string yes ID of the project owned by the authenticated user. 
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/1/export_relations/status"

The status can be one of the following:

  • 0: started
  • 1: finished

  • -1: failed

  • 0 - started
  • 1 - finished
  • -1 - failed 
[
  {
    "relation": "project_badges",
    "status": 1,
    "error": null,
    "updated_at": "2021-05-04T11:25:20.423Z"
  },
  {
    "relation": "boards",
    "status": 1,
    "error": null,
    "updated_at": "2021-05-04T11:25:20.085Z"
  }
]

Export download

Download the finished relations export:

GET /projects/:id/export_relations/download
Attribute Type Required Description
id integer/string yes ID of the project owned by the authenticated user.
relation string yes Name of the project top-level relation to download. 
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \
     --remote-name "https://gitlab.example.com/api/v4/projects/1/export_relations/download?relation=labels"

ls labels.ndjson.gz
labels.ndjson.gz