group_import_export.md 3.44 KB
Newer Older
George Koltsov's avatar
George Koltsov committed
1 2
# Group Import/Export API

3
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20353) in GitLab 12.8 as an experimental feature. May change in future releases.
George Koltsov's avatar
George Koltsov committed
4

5 6 7
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
8

9
Group exports include the following:
George Koltsov's avatar
George Koltsov committed
10

11 12 13 14 15 16
- 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
17 18 19 20 21

## Schedule new export

Start a new group export.

Amy Qualls's avatar
Amy Qualls committed
22
```plaintext
George Koltsov's avatar
George Koltsov committed
23 24 25 26 27
POST /groups/:id/export
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
28
| `id`      | integer/string | yes      | ID of the group owned by the authenticated user |
George Koltsov's avatar
George Koltsov committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60

```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/export
```

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

## Export download

Download the finished export.

```text
GET /groups/:id/export/download
```

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

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name https://gitlab.example.com/api/v4/groups/1/export/download
```

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

61 62 63 64 65
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
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87

## Import a file

```text
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
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
```
88 89 90 91 92 93 94 95 96

## 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.
97 98
- 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.