group_import_export.md 4.1 KB
Newer Older
Craig Norris's avatar
Craig Norris committed
1
---
2 3
stage: Manage
group: Import
4
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
Craig Norris's avatar
Craig Norris committed
5 6
---

George Koltsov's avatar
George Koltsov committed
7 8
# Group Import/Export API

9
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20353) in GitLab 12.8.
George Koltsov's avatar
George Koltsov committed
10

11 12 13
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.
George Koltsov's avatar
George Koltsov committed
14

15
Group exports include the following:
George Koltsov's avatar
George Koltsov committed
16

17 18 19 20 21 22
- Group milestones
- Group boards
- Group labels
- Group badges
- Group members
- Sub-groups. Each sub-group includes all data above
23
- Group wikis **(PREMIUM SELF)**
George Koltsov's avatar
George Koltsov committed
24 25 26 27 28

## Schedule new export

Start a new group export.

Amy Qualls's avatar
Amy Qualls committed
29
```plaintext
George Koltsov's avatar
George Koltsov committed
30 31 32 33 34
POST /groups/:id/export
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
35
| `id`      | integer/string | yes      | ID of the group owned by the authenticated user |
George Koltsov's avatar
George Koltsov committed
36 37

```shell
Greg Myers's avatar
Greg Myers committed
38
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/export"
George Koltsov's avatar
George Koltsov committed
39 40 41 42 43 44 45 46 47 48 49 50
```

```json
{
  "message": "202 Accepted"
}
```

## Export download

Download the finished export.

51
```plaintext
George Koltsov's avatar
George Koltsov committed
52 53 54 55 56 57 58 59
GET /groups/:id/export/download
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | ID of the group owned by the authenticated user |

```shell
Greg Myers's avatar
Greg Myers committed
60
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name "https://gitlab.example.com/api/v4/groups/1/export/download"
George Koltsov's avatar
George Koltsov committed
61 62 63 64 65 66 67
```

```shell
ls *export.tar.gz
2020-12-05_22-11-148_namespace_export.tar.gz
```

68 69 70 71 72
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
George Koltsov's avatar
George Koltsov committed
73 74 75

## Import a file

76
```plaintext
George Koltsov's avatar
George Koltsov committed
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
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
Greg Myers's avatar
Greg Myers committed
93
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"
George Koltsov's avatar
George Koltsov committed
94
```
95

96
NOTE:
97
The maximum import file size can be set by the Administrator, default is `0` (unlimited).
Marcel Amirault's avatar
Marcel Amirault committed
98
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.
Roger Meier's avatar
Roger Meier committed
99

100 101 102 103 104 105 106 107
## 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.
108 109
- 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.