project_import_export.md 7.1 KB
Newer Older
Travis Miller's avatar
Travis Miller committed
1
# Project import/export API
James Lopez's avatar
James Lopez committed
2 3 4

[Introduced][ce-41899] in GitLab 10.6

James Lopez's avatar
James Lopez committed
5
[See also the project import/export documentation](../user/project/settings/import_export.md)
James Lopez's avatar
James Lopez committed
6

Travis Miller's avatar
Travis Miller committed
7
## Schedule an export
8 9 10

Start a new export.

11 12 13 14 15 16 17 18
The endpoint also accepts an `upload` param. This param is a hash that contains
all the necessary information to upload the exported project to a web server or
to any S3-compatible platform. At the moment we only support binary
data file uploads to the final server.

If the `upload` params is present, `upload[url]` param is required.
 (**Note:** This feature was introduced in GitLab 10.7)

19 20 21 22 23 24 25
```http
POST /projects/:id/export
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
26
| `description`      | string | no | Overrides the project description |
27 28 29
| `upload`      | hash | no | Hash that contains the information to upload the exported project to a web server |
| `upload[url]`      | string | yes      | The URL to upload the project |
| `upload[http_method]`      | string | no      | The HTTP method to upload the exported project. Only `PUT` and `POST` methods allowed. Default is `PUT` |
30

31 32

```console
33
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/export \
34 35 36 37
    --data "upload[http_method]=PUT" \
    --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMBJHN2O62W8IELQ%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd"
```

38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
```json
{
  "message": "202 Accepted"
}
```

## Export status

Get the status of export.

```http
GET /projects/:id/export
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |

```console
57
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/export
58 59
```

60 61 62 63 64
Status can be one of `none`, `started`, `after_export_action` or `finished`. The
`after_export_action` state represents that the export process has been completed successfully and
the platform is performing some actions on the resulted file. For example, sending
an email notifying the user to download the file, uploading the exported file
to a web server, etc.
65

66 67
`_links` are only present when export has finished.

68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
```json
{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "export_status": "finished",
  "_links": {
    "api_url": "https://gitlab.example.com/api/v4/projects/1/export/download",
    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/download_export",
  }
}
```

## Export download

Download the finished export.

```http
Travis Miller's avatar
Travis Miller committed
90
GET /projects/:id/export/download
91 92 93 94 95 96 97
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |

```console
98
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name https://gitlab.example.com/api/v4/projects/5/export/download
99 100 101 102 103 104 105
```

```console
ls *export.tar.gz
2017-12-05_22-11-148_namespace_project_export.tar.gz
```

James Lopez's avatar
James Lopez committed
106 107 108 109 110 111 112 113
## Import a file

```http
POST /projects/import
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
James Lopez's avatar
James Lopez committed
114
| `namespace` | integer/string | no | The ID or path of the namespace that the project will be imported to. Defaults to the current user's namespace |
James Lopez's avatar
James Lopez committed
115 116
| `file` | string | yes | The file to be uploaded |
| `path` | string | yes | Name and path for new project |
117
| `overwrite` | boolean | no | If there is a project with the same path the import will overwrite it. Default to false |
James Ramsay's avatar
James Ramsay committed
118
| `override_params` | Hash | no | Supports all fields defined in the [Project API](projects.md) |
119

James Ramsay's avatar
James Ramsay committed
120
The override params passed will take precedence over all values defined inside the export file.
James Lopez's avatar
James Lopez committed
121

James Ramsay's avatar
James Ramsay committed
122
To upload a file from your file system, use the `--form` argument. This causes
James Lopez's avatar
James Lopez committed
123
cURL to post data using the header `Content-Type: multipart/form-data`.
James Ramsay's avatar
James Ramsay committed
124
The `file=` parameter must point to a file on your file system and be preceded
James Lopez's avatar
James Lopez committed
125 126 127
by `@`. For example:

```console
128
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "path=api-project" --form "file=@/path/to/file" https://gitlab.example.com/api/v4/projects/import
James Lopez's avatar
James Lopez committed
129 130
```

131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
cURL doesn't support posting a file from a remote server. Importing a project from a remote server can be accomplished through something like the following:

```python
import requests
import urllib
import json
import sys

s3_file = urllib.urlopen(presigned_url)

url =  'https://gitlab.example.com/api/v4/projects/import'
files = {'file': s3_file}
data = {
    "path": "example-project",
    "namespace": "example-group"
}
headers = {
148
    'Private-Token': "<your_access_token>"
149 150 151 152 153
}

requests.post(url, headers=headers, data=data, files=files)
```

James Lopez's avatar
James Lopez committed
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
```json
{
  "id": 1,
  "description": null,
  "name": "api-project",
  "name_with_namespace": "Administrator / api-project",
  "path": "api-project",
  "path_with_namespace": "root/api-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled"
}
```

## Import status

James Lopez's avatar
James Lopez committed
169
Get the status of an import.
James Lopez's avatar
James Lopez committed
170 171 172 173 174 175 176 177 178 179

```http
GET /projects/:id/import
```

| Attribute | Type           | Required | Description                              |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |

```console
180
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/import
James Lopez's avatar
James Lopez committed
181 182
```

James Lopez's avatar
James Lopez committed
183 184
Status can be one of `none`, `scheduled`, `failed`, `started`, or `finished`.

James Lopez's avatar
James Lopez committed
185
If the status is `failed`, it will include the import error message under `import_error`.
James Lopez's avatar
James Lopez committed
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200

```json
{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "import_status": "started"
}
```

[ce-41899]: https://gitlab.com/gitlab-org/gitlab-ce/issues/41899