Group import/export API

Introduced in GitLab 12.8.

Group Import/Export allows you to export group structure and import it to a new location. When used with Project Import/Export, you can preserve connections with group-level relationships, such as connections between project issues and group epics.

Group exports include the following:

  • Group milestones
  • Group boards
  • Group labels
  • Group badges
  • Group members
  • Subgroups. Each subgroup includes all data above
  • Group wikis

Schedule new export

Start a new group export.

POST /groups/:id/export
AttributeTypeRequiredDescription
idinteger/stringyesID of the group owned by the authenticated user
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/export"
{
  "message": "202 Accepted"
}

Export download

Download the finished export.

GET /groups/:id/export/download
AttributeTypeRequiredDescription
idinteger/stringyesID of the group owned by the authenticated user
group=1
token=secret
curl --request GET\
     --header "PRIVATE-TOKEN: ${token}" \
     --output download_group_${group}.tar.gz \
     "https://gitlab.example.com/api/v4/groups/${group}/export/download"
ls *export.tar.gz
2020-12-05_22-11-148_namespace_export.tar.gz

Time spent on exporting a group may vary depending on a size of the group. This endpoint returns either:

  • The exported archive (when available)
  • A 404 message

Import a file

POST /groups/import
AttributeTypeRequiredDescription
namestringyesThe name of the group to be imported
pathstringyesName and path for new group
filestringyesThe file to be uploaded
parent_idintegernoID of a parent group that the group will be imported into. Defaults to the current user’s namespace if not provided.

To upload a file from your file system, use the --form argument. This causes cURL to post data using the header Content-Type: multipart/form-data. The file= parameter must point to a file on your file system and be preceded by @. For example:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "name=imported-group" --form "path=imported-group" \
     --form "file=@/path/to/file" "https://gitlab.example.com/api/v4/groups/import"
note
The maximum import file size can be set by the Administrator, default is 0 (unlimited). As an administrator, you can modify the maximum import file size. To do so, use the max_import_size option in the Application settings API or the Admin Area. Default modified from 50MB to 0 in GitLab 13.8.

Important notes

Note the following:

  • To preserve group-level relationships from imported projects, run Group Import/Export first, to allow project imports into the desired group structure.
  • Imported groups are given a private visibility level, unless imported into a parent group.
  • If imported into a parent group, subgroups will inherit a similar level of visibility, unless otherwise restricted.
  • To preserve the member list and their respective permissions on imported groups, review the users in these groups. Make sure these users exist before importing the desired groups.