2020-10-26 17:08:22 -04:00
---
2020-11-17 10:09:28 -05:00
stage: Manage
group: Import
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-26 17:08:22 -04:00
---
2021-09-15 11:10:13 -04:00
# Group Import/Export API **(FREE)**
2020-02-11 04:08:39 -05:00
2020-05-08 11:09:28 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20353) in GitLab 12.8.
2020-02-11 04:08:39 -05:00
2020-02-26 22:08:49 -05:00
Group Import/Export allows you to export group structure and import it to a new location.
When used with [Project Import/Export ](project_import_export.md ), you can preserve connections with
group-level relationships, such as connections between project issues and group epics.
2020-02-11 04:08:39 -05:00
2020-02-26 22:08:49 -05:00
Group exports include the following:
2020-02-11 04:08:39 -05:00
2020-02-26 22:08:49 -05:00
- Group milestones
- Group boards
- Group labels
- Group badges
- Group members
2021-02-16 19:09:19 -05:00
- Subgroups. Each subgroup includes all data above
2021-02-16 13:09:24 -05:00
- Group wikis ** (PREMIUM SELF)**
2020-02-11 04:08:39 -05:00
## Schedule new export
Start a new group export.
2020-02-27 04:09:01 -05:00
```plaintext
2020-02-11 04:08:39 -05:00
POST /groups/:id/export
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
2020-04-21 14:09:31 -04:00
| `id` | integer/string | yes | ID of the group owned by the authenticated user |
2020-02-11 04:08:39 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/1/export"
2020-02-11 04:08:39 -05:00
```
```json
{
"message": "202 Accepted"
}
```
## Export download
Download the finished export.
2020-05-19 23:08:04 -04:00
```plaintext
2020-02-11 04:08:39 -05:00
GET /groups/:id/export/download
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | ID of the group owned by the authenticated user |
```shell
2021-09-28 14:11:27 -04:00
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"
2020-02-11 04:08:39 -05:00
```
```shell
ls *export.tar.gz
2020-12-05_22-11-148_namespace_export.tar.gz
```
2020-02-26 22:08:49 -05:00
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
2020-02-11 04:08:39 -05:00
## Import a file
2020-05-19 23:08:04 -04:00
```plaintext
2020-02-11 04:08:39 -05:00
POST /groups/import
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `name` | string | yes | The name of the group to be imported |
| `path` | string | yes | Name and path for new group |
| `file` | string | yes | The file to be uploaded |
| `parent_id` | integer | no | ID 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:
```shell
2021-06-02 11:09:59 -04:00
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"
2020-02-11 04:08:39 -05:00
```
2020-02-26 22:08:49 -05:00
2020-12-04 16:09:29 -05:00
NOTE:
2021-01-13 16:11:00 -05:00
The maximum import file size can be set by the Administrator, default is `0` (unlimited).
2021-02-15 19:09:01 -05:00
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 ](settings.md#change-application-settings ) or the [Admin Area ](../user/admin_area/settings/account_and_limit_settings.md ). Default [modified ](https://gitlab.com/gitlab-org/gitlab/-/issues/251106 ) from 50MB to 0 in GitLab 13.8.
2020-06-09 11:08:05 -04:00
2020-02-26 22:08:49 -05:00
## 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.
2020-03-24 20:08:11 -04:00
- 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.