group_import_export.md 3.95 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
George Koltsov's avatar
George Koltsov committed
23 24 25 26 27

## Schedule new export

Start a new group export.

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

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

```shell
Greg Myers's avatar
Greg Myers committed
37
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
38 39 40 41 42 43 44 45 46 47 48 49
```

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

## Export download

Download the finished export.

50
```plaintext
George Koltsov's avatar
George Koltsov committed
51 52 53 54 55 56 57 58
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
59
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
60 61 62 63 64 65 66
```

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

67 68 69 70 71
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
72 73 74

## Import a file

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

95
NOTE:
Roger Meier's avatar
Roger Meier committed
96 97 98
The maximum import file size can be set by the Administrator, default is 50MB.
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 UI](../user/admin_area/settings/account_and_limit_settings.md).

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