projects.md 93.4 KB
Newer Older
1 2 3 4 5 6
---
stage: Plan
group: Project Management
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/#designated-technical-writers
---

7
# Projects API
8

9
## Project visibility level
10

11 12
Project in GitLab can be either private, internal or public.
This is determined by the `visibility` field in the project.
13

14
Values for the project visibility level are:
15

16
- `private`:
17
  Project access must be granted explicitly for each user.
18
- `internal`:
19
  The project can be cloned by any logged in user.
20
- `public`:
21
  The project can be accessed without any authentication.
22

23 24 25 26
## Project merge method

There are currently three options for `merge_method` to choose from:

27
- `merge`:
28
  A merge commit is created for every merge, and merging is allowed as long as there are no conflicts.
29
- `rebase_merge`:
30 31
  A merge commit is created for every merge, but merging is only allowed if fast-forward merge is possible.
  This way you could make sure that if this merge request would build, after merging to target branch it would also build.
32
- `ff`:
33 34
  No merge commits are created and all merges are fast-forwarded, which means that merging is only allowed if the branch could be fast-forwarded.

35
## List all projects
Nihad Abbasov's avatar
Nihad Abbasov committed
36

37
Get a list of all visible projects across GitLab for the authenticated user.
38
When accessed without authentication, only public projects with "simple" fields are returned.
Nihad Abbasov's avatar
Nihad Abbasov committed
39

40
```plaintext
Nihad Abbasov's avatar
Nihad Abbasov committed
41 42 43
GET /projects
```

44 45
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
46 47
| `archived`                    | boolean  | no | Limit by archived status |
| `visibility`                  | string   | no | Limit by visibility `public`, `internal`, or `private` |
48
| `order_by`                    | string   | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. `repository_size`, `storage_size`, or `wiki_size` fields are only allowed for admins. Default is `created_at` |
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
| `sort`                        | string   | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
| `search`                      | string   | no | Return list of projects matching the search criteria |
| `search_namespaces`           | boolean  | no | Include ancestor namespaces when matching search criteria. Default is `false` |
| `simple`                      | boolean  | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. |
| `owned`                       | boolean  | no | Limit by projects explicitly owned by the current user |
| `membership`                  | boolean  | no | Limit by projects that the current user is a member of |
| `starred`                     | boolean  | no | Limit by projects starred by the current user |
| `statistics`                  | boolean  | no | Include project statistics |
| `with_custom_attributes`      | boolean  | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
| `with_issues_enabled`         | boolean  | no | Limit by enabled issues feature |
| `with_merge_requests_enabled` | boolean  | no | Limit by enabled merge requests feature |
| `with_programming_language`   | string   | no | Limit by projects which use the given programming language |
| `wiki_checksum_failed`        | boolean  | no | **(PREMIUM)** Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) |
| `repository_checksum_failed`  | boolean  | no | **(PREMIUM)** Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) |
| `min_access_level`            | integer  | no | Limit by current user minimal [access level](members.md) |
| `id_after`                    | integer  | no | Limit results to projects with IDs greater than the specified ID |
| `id_before`                   | integer  | no | Limit results to projects with IDs less than the specified ID |
| `last_activity_after`         | datetime | no | Limit results to projects with last_activity after specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
| `last_activity_before`        | datetime | no | Limit results to projects with last_activity before specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
68
| `repository_storage`          | string   | no | Limit results to projects stored on repository_storage. Available for admins only. |
vanadium23's avatar
vanadium23 committed
69

70 71 72
NOTE: **Note:**
This endpoint supports [keyset pagination](README.md#keyset-based-pagination) for selected `order_by` options.

73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
When `simple=true` or the user is unauthenticated this returns something like:

```json
[
  {
    "id": 4,
    "description": null,
    "default_branch": "master",
    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
    "web_url": "http://example.com/diaspora/diaspora-client",
    "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md",
    "tag_list": [
      "example",
      "disapora client"
    ],
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "forks_count": 0,
    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
    "star_count": 0,
  },
  {
    "id": 6,
    "description": null,
    "default_branch": "master",
...
```

When the user is authenticated and `simple` is not set this returns something like:

vanadium23's avatar
vanadium23 committed
108 109 110 111 112 113 114 115 116 117
```json
[
  {
    "id": 4,
    "description": null,
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
    "web_url": "http://example.com/diaspora/diaspora-client",
118
    "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md",
vanadium23's avatar
vanadium23 committed
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
    "tag_list": [
      "example",
      "disapora client"
    ],
    "owner": {
      "id": 3,
      "name": "Diaspora",
      "created_at": "2013-09-30T13:46:02Z"
    },
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
138
    "can_create_merge_request_in": true,
139
    "resolve_outdated_diff_discussions": false,
vanadium23's avatar
vanadium23 committed
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
    "container_registry_enabled": false,
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora"
    },
    "import_status": "none",
    "archived": false,
    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
    "shared_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
158
    "ci_default_git_depth": 50,
vanadium23's avatar
vanadium23 committed
159 160 161
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
162
    "allow_merge_on_skipped_pipeline": false,
vanadium23's avatar
vanadium23 committed
163
    "only_allow_merge_if_all_discussions_are_resolved": false,
164
    "remove_source_branch_after_merge": false,
vanadium23's avatar
vanadium23 committed
165
    "request_access_enabled": false,
166
    "merge_method": "merge",
167
    "autoclose_referenced_issues": true,
168
    "suggestion_commit_message": null,
169
    "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
170
    "marked_for_deletion_on": "2020-04-03",
vanadium23's avatar
vanadium23 committed
171 172 173 174
    "statistics": {
      "commit_count": 37,
      "storage_size": 1038090,
      "repository_size": 1038090,
175
      "wiki_size" : 0,
vanadium23's avatar
vanadium23 committed
176
      "lfs_objects_size": 0,
177 178
      "job_artifacts_size": 0,
      "packages_size": 0
179 180 181 182 183 184 185 186 187 188
    },
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members"
    },
vanadium23's avatar
vanadium23 committed
189 190 191 192 193 194 195 196 197
  },
  {
    "id": 6,
    "description": null,
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
    "web_url": "http://example.com/brightbox/puppet",
198
    "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md",
vanadium23's avatar
vanadium23 committed
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
    "tag_list": [
      "example",
      "puppet"
    ],
    "owner": {
      "id": 4,
      "name": "Brightbox",
      "created_at": "2013-09-30T13:46:02Z"
    },
    "name": "Puppet",
    "name_with_namespace": "Brightbox / Puppet",
    "path": "puppet",
    "path_with_namespace": "brightbox/puppet",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
218
    "can_create_merge_request_in": true,
219
    "resolve_outdated_diff_discussions": false,
vanadium23's avatar
vanadium23 committed
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
    "container_registry_enabled": false,
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 4,
      "name": "Brightbox",
      "path": "brightbox",
      "kind": "group",
      "full_path": "brightbox"
    },
    "import_status": "none",
    "import_error": null,
    "permissions": {
      "project_access": {
        "access_level": 10,
        "notification_level": 3
      },
      "group_access": {
        "access_level": 50,
        "notification_level": 3
      }
    },
    "archived": false,
    "avatar_url": null,
    "shared_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
249
    "ci_default_git_depth": 0,
vanadium23's avatar
vanadium23 committed
250 251 252
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
253
    "allow_merge_on_skipped_pipeline": false,
vanadium23's avatar
vanadium23 committed
254
    "only_allow_merge_if_all_discussions_are_resolved": false,
255
    "remove_source_branch_after_merge": false,
vanadium23's avatar
vanadium23 committed
256
    "request_access_enabled": false,
257
    "merge_method": "merge",
258 259 260 261 262 263 264 265 266 267 268 269 270
    "auto_devops_enabled": true,
    "auto_devops_deploy_strategy": "continuous",
    "repository_storage": "default",
    "approvals_before_merge": 0,
    "mirror": false,
    "mirror_user_id": 45,
    "mirror_trigger_builds": false,
    "only_mirror_protected_branches": false,
    "mirror_overwrites_diverged_branches": false,
    "external_authorization_classification_label": null,
    "packages_enabled": true,
    "service_desk_enabled": false,
    "service_desk_address": null,
271
    "autoclose_referenced_issues": true,
272
    "suggestion_commit_message": null,
vanadium23's avatar
vanadium23 committed
273 274 275 276
    "statistics": {
      "commit_count": 12,
      "storage_size": 2066080,
      "repository_size": 2066080,
277
      "wiki_size" : 0,
vanadium23's avatar
vanadium23 committed
278
      "lfs_objects_size": 0,
279 280
      "job_artifacts_size": 0,
      "packages_size": 0
281 282 283 284 285 286 287 288 289
    },
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members"
vanadium23's avatar
vanadium23 committed
290 291 292 293 294
    }
  }
]
```

295
NOTE: **Note:**
296
For users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) the `marked_for_deletion_at` attribute has been deprecated and will be removed in API v5 in favor of the `marked_for_deletion_on` attribute.
297

298 299 300 301 302 303 304 305 306 307 308 309 310 311
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:

```json
[
  {
    "id": 4,
    "description": null,
    "approvals_before_merge": 0,
    ...
  }
]
```

312 313
You can filter by [custom attributes](custom_attributes.md) with:

314
```plaintext
315 316 317
GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```

318 319
### Pagination limits

320
From GitLab 13.0, [offset-based pagination](README.md#offset-based-pagination) will be
321
[limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565).
322 323 324 325 326
[Keyset pagination](README.md#keyset-based-pagination) will be required to retrieve projects
beyond this limit.

Note that keyset pagination only supports `order_by=id`. Other sorting options are not available.

327
## List user projects
vanadium23's avatar
vanadium23 committed
328

Davin Walker's avatar
Davin Walker committed
329
Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned.
vanadium23's avatar
vanadium23 committed
330

331
```plaintext
vanadium23's avatar
vanadium23 committed
332 333 334 335 336 337 338 339 340 341 342
GET /users/:user_id/projects
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `user_id` | string | yes | The ID or username of the user |
| `archived` | boolean | no | Limit by archived status |
| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` |
| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Return list of projects matching the search criteria |
343
| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. |
344
| `owned` | boolean | no | Limit by projects explicitly owned by the current user |
vanadium23's avatar
vanadium23 committed
345 346 347
| `membership` | boolean | no | Limit by projects that the current user is a member of |
| `starred` | boolean | no | Limit by projects starred by the current user |
| `statistics` | boolean | no | Include project statistics |
348
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
349 350
| `with_issues_enabled` | boolean | no | Limit by enabled issues feature |
| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature |
351
| `with_programming_language` | string | no | Limit by projects which use the given programming language |
352
| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) |
353 354
| `id_after`                    | integer | no | Limit results to projects with IDs greater than the specified ID |
| `id_before`                   | integer | no | Limit results to projects with IDs less than the specified ID |
355

356 357 358
NOTE: **Note:**
This endpoint supports [keyset pagination](README.md#keyset-based-pagination) for selected `order_by` options.

Nihad Abbasov's avatar
Nihad Abbasov committed
359 360 361
```json
[
  {
Marin Jankovski's avatar
Marin Jankovski committed
362
    "id": 4,
Nihad Abbasov's avatar
Nihad Abbasov committed
363 364
    "description": null,
    "default_branch": "master",
365
    "visibility": "private",
Marin Jankovski's avatar
Marin Jankovski committed
366 367 368
    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
    "web_url": "http://example.com/diaspora/diaspora-client",
369
    "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md",
370 371 372 373
    "tag_list": [
      "example",
      "disapora client"
    ],
Nihad Abbasov's avatar
Nihad Abbasov committed
374
    "owner": {
Marin Jankovski's avatar
Marin Jankovski committed
375 376
      "id": 3,
      "name": "Diaspora",
Ben Boeckel's avatar
Ben Boeckel committed
377
      "created_at": "2013-09-30T13:46:02Z"
Nihad Abbasov's avatar
Nihad Abbasov committed
378
    },
Marin Jankovski's avatar
Marin Jankovski committed
379 380 381 382 383
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "issues_enabled": true,
384
    "open_issues_count": 1,
Marin Jankovski's avatar
Marin Jankovski committed
385
    "merge_requests_enabled": true,
386
    "jobs_enabled": true,
Nihad Abbasov's avatar
Nihad Abbasov committed
387
    "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
388
    "snippets_enabled": false,
389
    "can_create_merge_request_in": true,
390
    "resolve_outdated_diff_discussions": false,
391
    "container_registry_enabled": false,
Ben Boeckel's avatar
Ben Boeckel committed
392 393
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
394
    "creator_id": 3,
Marin Jankovski's avatar
Marin Jankovski committed
395 396 397 398
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
399 400
      "kind": "group",
      "full_path": "diaspora"
401
    },
402
    "import_status": "none",
sue445's avatar
sue445 committed
403
    "archived": false,
Tomasz Maczukin's avatar
Tomasz Maczukin committed
404 405 406
    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
    "shared_runners_enabled": true,
    "forks_count": 0,
407 408
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
409
    "ci_default_git_depth": 50,
410
    "public_jobs": true,
411
    "shared_with_groups": [],
412
    "only_allow_merge_if_pipeline_succeeds": false,
413
    "allow_merge_on_skipped_pipeline": false,
414
    "only_allow_merge_if_all_discussions_are_resolved": false,
415
    "remove_source_branch_after_merge": false,
416
    "request_access_enabled": false,
417
    "merge_method": "merge",
418
    "autoclose_referenced_issues": true,
419
    "suggestion_commit_message": null,
420
    "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
421
    "marked_for_deletion_on": "2020-04-03",
422 423 424 425
    "statistics": {
      "commit_count": 37,
      "storage_size": 1038090,
      "repository_size": 1038090,
426
      "wiki_size" : 0,
427
      "lfs_objects_size": 0,
428 429
      "job_artifacts_size": 0,
      "packages_size": 0
430 431 432 433 434 435 436 437 438
    },
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members"
439
    }
Nihad Abbasov's avatar
Nihad Abbasov committed
440 441
  },
  {
Marin Jankovski's avatar
Marin Jankovski committed
442
    "id": 6,
Nihad Abbasov's avatar
Nihad Abbasov committed
443
    "description": null,
Marin Jankovski's avatar
Marin Jankovski committed
444
    "default_branch": "master",
445
    "visibility": "private",
Marin Jankovski's avatar
Marin Jankovski committed
446 447 448
    "ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
    "web_url": "http://example.com/brightbox/puppet",
449
    "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md",
450 451 452 453
    "tag_list": [
      "example",
      "puppet"
    ],
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
454
    "owner": {
Marin Jankovski's avatar
Marin Jankovski committed
455 456 457
      "id": 4,
      "name": "Brightbox",
      "created_at": "2013-09-30T13:46:02Z"
Nihad Abbasov's avatar
Nihad Abbasov committed
458
    },
Marin Jankovski's avatar
Marin Jankovski committed
459 460 461 462
    "name": "Puppet",
    "name_with_namespace": "Brightbox / Puppet",
    "path": "puppet",
    "path_with_namespace": "brightbox/puppet",
Nihad Abbasov's avatar
Nihad Abbasov committed
463
    "issues_enabled": true,
464
    "open_issues_count": 1,
Nihad Abbasov's avatar
Nihad Abbasov committed
465
    "merge_requests_enabled": true,
466
    "jobs_enabled": true,
Nihad Abbasov's avatar
Nihad Abbasov committed
467
    "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
468
    "snippets_enabled": false,
469
    "can_create_merge_request_in": true,
470
    "resolve_outdated_diff_discussions": false,
471
    "container_registry_enabled": false,
Marin Jankovski's avatar
Marin Jankovski committed
472 473
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
474
    "creator_id": 3,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
475
    "namespace": {
Marin Jankovski's avatar
Marin Jankovski committed
476 477 478
      "id": 4,
      "name": "Brightbox",
      "path": "brightbox",
479 480
      "kind": "group",
      "full_path": "brightbox"
481
    },
482 483
    "import_status": "none",
    "import_error": null,
484 485 486 487 488 489 490 491 492 493
    "permissions": {
      "project_access": {
        "access_level": 10,
        "notification_level": 3
      },
      "group_access": {
        "access_level": 50,
        "notification_level": 3
      }
    },
sue445's avatar
sue445 committed
494
    "archived": false,
Tomasz Maczukin's avatar
Tomasz Maczukin committed
495 496 497 498
    "avatar_url": null,
    "shared_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
499
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
500
    "ci_default_git_depth": 0,
501
    "public_jobs": true,
502
    "shared_with_groups": [],
503
    "only_allow_merge_if_pipeline_succeeds": false,
504
    "allow_merge_on_skipped_pipeline": false,
505
    "only_allow_merge_if_all_discussions_are_resolved": false,
506
    "remove_source_branch_after_merge": false,
507
    "request_access_enabled": false,
508
    "merge_method": "merge",
509 510 511 512 513 514 515 516 517 518 519 520 521
    "auto_devops_enabled": true,
    "auto_devops_deploy_strategy": "continuous",
    "repository_storage": "default",
    "approvals_before_merge": 0,
    "mirror": false,
    "mirror_user_id": 45,
    "mirror_trigger_builds": false,
    "only_mirror_protected_branches": false,
    "mirror_overwrites_diverged_branches": false,
    "external_authorization_classification_label": null,
    "packages_enabled": true,
    "service_desk_enabled": false,
    "service_desk_address": null,
522
    "autoclose_referenced_issues": true,
523
    "suggestion_commit_message": null,
524 525 526 527
    "statistics": {
      "commit_count": 12,
      "storage_size": 2066080,
      "repository_size": 2066080,
528
      "wiki_size" : 0,
529
      "lfs_objects_size": 0,
530 531
      "job_artifacts_size": 0,
      "packages_size": 0
532 533 534 535 536 537 538 539 540
    },
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members"
541
    }
542 543 544 545
  }
]
```

546 547 548 549
## List projects starred by a user

Get a list of visible projects owned by the given user. When accessed without authentication, only public projects are returned.

550
```plaintext
551 552 553 554 555
GET /users/:user_id/starred_projects
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Camil Staps's avatar
Camil Staps committed
556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571
| `user_id` | string | yes | The ID or username of the user. |
| `archived` | boolean | no | Limit by archived status. |
| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private`. |
| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. |
| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc`. |
| `search` | string | no | Return list of projects matching the search criteria. |
| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned.. |
| `owned` | boolean | no | Limit by projects explicitly owned by the current user. |
| `membership` | boolean | no | Limit by projects that the current user is a member of. |
| `starred` | boolean | no | Limit by projects starred by the current user. |
| `statistics` | boolean | no | Include project statistics. |
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). |
| `with_issues_enabled` | boolean | no | Limit by enabled issues feature. |
| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature. |
| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md). |

572
```shell
Camil Staps's avatar
Camil Staps committed
573 574 575 576
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/5/starred_projects"
```

Example response:
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607

```json
[
  {
    "id": 4,
    "description": null,
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
    "web_url": "http://example.com/diaspora/diaspora-client",
    "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md",
    "tag_list": [
      "example",
      "disapora client"
    ],
    "owner": {
      "id": 3,
      "name": "Diaspora",
      "created_at": "2013-09-30T13:46:02Z"
    },
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
608
    "can_create_merge_request_in": true,
609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false,
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora"
    },
    "import_status": "none",
    "archived": false,
    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
    "shared_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
631
    "allow_merge_on_skipped_pipeline": false,
632
    "only_allow_merge_if_all_discussions_are_resolved": false,
633
    "remove_source_branch_after_merge": false,
634 635
    "request_access_enabled": false,
    "merge_method": "merge",
636
    "autoclose_referenced_issues": true,
637
    "suggestion_commit_message": null,
638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682
    "statistics": {
      "commit_count": 37,
      "storage_size": 1038090,
      "repository_size": 1038090,
      "lfs_objects_size": 0,
      "job_artifacts_size": 0
    },
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members"
    }
  },
  {
    "id": 6,
    "description": null,
    "default_branch": "master",
    "visibility": "private",
    "ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
    "web_url": "http://example.com/brightbox/puppet",
    "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md",
    "tag_list": [
      "example",
      "puppet"
    ],
    "owner": {
      "id": 4,
      "name": "Brightbox",
      "created_at": "2013-09-30T13:46:02Z"
    },
    "name": "Puppet",
    "name_with_namespace": "Brightbox / Puppet",
    "path": "puppet",
    "path_with_namespace": "brightbox/puppet",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
683
    "can_create_merge_request_in": true,
684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false,
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 4,
      "name": "Brightbox",
      "path": "brightbox",
      "kind": "group",
      "full_path": "brightbox"
    },
    "import_status": "none",
    "import_error": null,
    "permissions": {
      "project_access": {
        "access_level": 10,
        "notification_level": 3
      },
      "group_access": {
        "access_level": 50,
        "notification_level": 3
      }
    },
    "archived": false,
    "avatar_url": null,
    "shared_runners_enabled": true,
    "forks_count": 0,
    "star_count": 0,
    "runners_token": "b8547b1dc37721d05889db52fa2f02",
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
717
    "allow_merge_on_skipped_pipeline": false,
718
    "only_allow_merge_if_all_discussions_are_resolved": false,
719
    "remove_source_branch_after_merge": false,
720 721
    "request_access_enabled": false,
    "merge_method": "merge",
722 723 724 725 726 727 728 729 730 731 732 733 734
    "auto_devops_enabled": true,
    "auto_devops_deploy_strategy": "continuous",
    "repository_storage": "default",
    "approvals_before_merge": 0,
    "mirror": false,
    "mirror_user_id": 45,
    "mirror_trigger_builds": false,
    "only_mirror_protected_branches": false,
    "mirror_overwrites_diverged_branches": false,
    "external_authorization_classification_label": null,
    "packages_enabled": true,
    "service_desk_enabled": false,
    "service_desk_address": null,
735
    "autoclose_referenced_issues": true,
736
    "suggestion_commit_message": null,
737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756
    "statistics": {
      "commit_count": 12,
      "storage_size": 2066080,
      "repository_size": 2066080,
      "lfs_objects_size": 0,
      "job_artifacts_size": 0
    },
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members"
    }
  }
]
```

757
## Get single project
Nihad Abbasov's avatar
Nihad Abbasov committed
758

759 760
Get a specific project. This endpoint can be accessed without authentication if
the project is publicly accessible.
Nihad Abbasov's avatar
Nihad Abbasov committed
761

762
```plaintext
Nihad Abbasov's avatar
Nihad Abbasov committed
763 764 765
GET /projects/:id
```

766 767
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
768
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
769
| `statistics` | boolean | no | Include project statistics |
770
| `license` | boolean | no | Include project license data |
771
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
Nihad Abbasov's avatar
Nihad Abbasov committed
772

773 774
```json
{
775 776
  "id": 3,
  "description": null,
Marin Jankovski's avatar
Marin Jankovski committed
777
  "default_branch": "master",
778 779 780 781 782
  "visibility": "private",
  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
783
  "tag_list": [
784 785
    "example",
    "disapora project"
786
  ],
787 788 789 790
  "owner": {
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13:46:02Z"
791
  },
792 793 794 795
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
796
  "issues_enabled": true,
797
  "open_issues_count": 1,
798 799
  "merge_requests_enabled": true,
  "jobs_enabled": true,
800 801
  "wiki_enabled": true,
  "snippets_enabled": false,
802
  "can_create_merge_request_in": true,
803 804
  "resolve_outdated_diff_discussions": false,
  "container_registry_enabled": false,
805 806 807 808 809
  "container_expiration_policy": {
    "cadence": "7d",
    "enabled": false,
    "keep_n": null,
    "older_than": null,
810 811 812
    "name_regex": null, // to be deprecated in GitLab 13.0 in favor of `name_regex_delete`
    "name_regex_delete": null,
    "name_regex_keep": null,
813 814
    "next_run_at": "2020-01-07T21:42:58.658Z"
  },
815 816 817 818 819 820 821 822 823 824 825 826
  "created_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
    "kind": "group",
    "full_path": "diaspora",
    "avatar_url": "http://localhost:3000/uploads/group/avatar/3/foo.jpg",
    "web_url": "http://localhost:3000/groups/diaspora"
  },
827 828
  "import_status": "none",
  "import_error": null,
829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852
  "permissions": {
    "project_access": {
      "access_level": 10,
      "notification_level": 3
    },
    "group_access": {
      "access_level": 50,
      "notification_level": 3
    }
  },
  "archived": false,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  },
  "shared_runners_enabled": true,
  "forks_count": 0,
  "star_count": 0,
  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
853
  "ci_default_git_depth": 50,
854
  "public_jobs": true,
855
  "shared_with_groups": [
856 857 858 859 860 861
    {
      "group_id": 4,
      "group_name": "Twitter",
      "group_full_path": "twitter",
      "group_access_level": 30
    },
862 863
    {
      "group_id": 3,
864 865 866
      "group_name": "Gitlab Org",
      "group_full_path": "gitlab-org",
      "group_access_level": 10
867
    }
868
  ],
869
  "repository_storage": "default",
870
  "only_allow_merge_if_pipeline_succeeds": false,
871
  "allow_merge_on_skipped_pipeline": false,
872
  "only_allow_merge_if_all_discussions_are_resolved": false,
873
  "remove_source_branch_after_merge": false,
874 875
  "printing_merge_requests_link_enabled": true,
  "request_access_enabled": false,
876
  "merge_method": "merge",
877 878 879 880 881 882 883 884 885 886 887 888 889
  "auto_devops_enabled": true,
  "auto_devops_deploy_strategy": "continuous",
  "repository_storage": "default",
  "approvals_before_merge": 0,
  "mirror": false,
  "mirror_user_id": 45,
  "mirror_trigger_builds": false,
  "only_mirror_protected_branches": false,
  "mirror_overwrites_diverged_branches": false,
  "external_authorization_classification_label": null,
  "packages_enabled": true,
  "service_desk_enabled": false,
  "service_desk_address": null,
890
  "autoclose_referenced_issues": true,
891
  "suggestion_commit_message": null,
892
  "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
893
  "marked_for_deletion_on": "2020-04-03",
894
  "compliance_frameworks": [ "sox" ],
895 896 897 898
  "statistics": {
    "commit_count": 37,
    "storage_size": 1038090,
    "repository_size": 1038090,
899
    "wiki_size" : 0,
900
    "lfs_objects_size": 0,
901 902
    "job_artifacts_size": 0,
    "packages_size": 0
903 904 905 906 907 908 909 910 911
  },
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members"
912
  }
913 914 915
}
```

916 917 918 919 920 921 922 923 924 925 926 927
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:

```json
{
  "id": 3,
  "description": null,
  "approvals_before_merge": 0,
  ...
}
```

Suzanne Selhorn's avatar
Suzanne Selhorn committed
928
**Note**: The `web_url` and `avatar_url` attributes on `namespace` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27427) in GitLab 11.11.
929

930 931 932 933 934 935 936 937 938 939 940 941 942 943
If the project is a fork, and you provide a valid token to authenticate, the
`forked_from_project` field will appear in the response.

```json
{
   "id":3,

   ...

   "forked_from_project":{
      "id":13083,
      "description":"GitLab Community Edition",
      "name":"GitLab Community Edition",
      "name_with_namespace":"GitLab.org / GitLab Community Edition",
944 945
      "path":"gitlab-foss",
      "path_with_namespace":"gitlab-org/gitlab-foss",
946 947 948
      "created_at":"2013-09-26T06:02:36.000Z",
      "default_branch":"master",
      "tag_list":[],
949
      "ssh_url_to_repo":"git@gitlab.com:gitlab-org/gitlab-foss.git",
950 951
      "http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-foss.git",
      "web_url":"https://gitlab.com/gitlab-org/gitlab-foss",
952
      "avatar_url":"https://assets.gitlab-static.net/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png",
953
      "license_url": "https://gitlab.com/gitlab-org/gitlab/blob/master/LICENSE",
954 955 956 957 958 959 960
      "license": {
        "key": "mit",
        "name": "MIT License",
        "nickname": null,
        "html_url": "http://choosealicense.com/licenses/mit/",
        "source_url": "https://opensource.org/licenses/MIT",
      },
961 962
      "star_count":3812,
      "forks_count":3561,
963 964 965 966 967 968 969 970 971
      "last_activity_at":"2018-01-02T11:40:26.570Z",
      "namespace": {
            "id": 72,
            "name": "GitLab.org",
            "path": "gitlab-org",
            "kind": "group",
            "full_path": "gitlab-org",
            "parent_id": null
      }
972 973 974 975 976 977 978
   }

   ...

}
```

979
## Get project users
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
980

981
Get the users list of a project.
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
982

983
```plaintext
984 985
GET /projects/:id/users
```
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
986

987 988
| Attribute    | Type          | Required | Description |
| ------------ | ------------- | -------- | ----------- |
989
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
990 991
| `search`     | string        | no       | Search for specific users |
| `skip_users` | integer array | no       | Filter out users with the specified IDs |
992

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
993
```json
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
994 995
[
  {
996 997 998 999 1000 1001
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
    "web_url": "http://localhost:3000/john_smith"
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
1002
  },
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
1003
  {
1004 1005 1006 1007 1008 1009
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
    "web_url": "http://localhost:3000/jack_smith"
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
1010 1011
  }
]
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
1012 1013
```

1014
## Get project events
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
1015

1016
Please refer to the [Events API documentation](events.md#list-a-projects-visible-events).
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
1017

1018
## Create project
1019

1020
Creates a new project owned by the authenticated user.
1021

1022
```plaintext
1023 1024 1025
POST /projects
```

1026 1027
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1028 1029
| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
| `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated lowercased with dashes). |
1030
| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) |
1031
| `default_branch` | string | no | `master` by default |
1032
| `description` | string | no | Short project description |
1033 1034 1035 1036 1037 1038 1039 1040
| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead |
| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead |
| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead |
| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead |
| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead |
| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1041
| `forking_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1042 1043 1044
| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1045
| `pages_access_level` | string | no | One of `disabled`, `private`, `enabled` or `public` |
1046
| `emails_disabled` | boolean | no | Disable email notifications |
1047
| `show_default_award_emojis` | boolean | no | Show default award emojis |
1048
| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
1049
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
1050
| `container_expiration_policy_attributes` | hash | no | Update the image expiration policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) |
1051
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
1052
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
1053
| `import_url` | string | no | URL to import repository from |
1054
| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members |
1055
| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs |
1056
| `allow_merge_on_skipped_pipeline` | boolean | no | Set whether or not merge requests can be merged with skipped jobs |
1057
| `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved |
1058
| `merge_method` | string | no | Set the [merge method](#project-merge-method) used |
1059
| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch |
1060
| `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests |
1061 1062
| `lfs_enabled` | boolean | no | Enable LFS |
| `request_access_enabled` | boolean | no | Allow users to request member access |
1063
| `tag_list`    | array   | no       | The list of tags for a project; put array of tags, that should be finally assigned to a project |
1064
| `avatar`    | mixed   | no      | Image file for avatar of the project                |
1065
| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
1066
| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` |
1067
| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) |
1068
| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled |
1069
| `build_coverage_regex` | string | no | Test coverage parsing |
1070
| `ci_config_path` | string | no | The path to CI config file |
1071 1072
| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project |
| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) |
1073
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
1074
| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge requests by default |
1075
| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project |
1076 1077
| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project |
| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds |
Steve's avatar
Steve committed
1078
| `initialize_with_readme` | boolean | no | `false` by default |
1079
| `template_name` | string | no | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template |
1080
| `template_project_id` | integer | no | **(PREMIUM)** When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. |
1081 1082
| `use_custom_template` | boolean | no | **(PREMIUM)** Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template |
| `group_with_project_templates_id` | integer | no | **(PREMIUM)** For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires `use_custom_template` to be true |
Mitar's avatar
Mitar committed
1083
| `packages_enabled` | boolean | no | **(PREMIUM ONLY)** Enable or disable packages repository feature |
1084

1085
NOTE: **Note:** If your HTTP repository is not publicly accessible,
1086 1087 1088
add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
where `password` is a public access key with the `api` scope enabled.

1089
## Create project for user
1090

1091
Creates a new project owned by the specified user. Available only for admins.
1092

1093
```plaintext
1094 1095 1096
POST /projects/user/:user_id
```

1097 1098 1099 1100 1101 1102 1103
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `user_id` | integer | yes | The user ID of the project owner |
| `name` | string | yes | The name of the new project |
| `path` | string | no | Custom repository name for new project. By default generated based on name |
| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) |
| `description` | string | no | Short project description |
1104 1105 1106 1107 1108 1109 1110 1111
| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead |
| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead |
| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead |
| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead |
| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead |
| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1112
| `forking_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1113 1114 1115
| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1116
| `pages_access_level` | string | no | One of `disabled`, `private`, `enabled` or `public` |
1117
| `emails_disabled` | boolean | no | Disable email notifications |
1118
| `show_default_award_emojis` | boolean | no | Show default award emojis |
1119
| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
1120 1121
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
1122
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
1123
| `import_url` | string | no | URL to import repository from |
1124
| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members |
1125
| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs |
1126
| `allow_merge_on_skipped_pipeline` | boolean | no | Set whether or not merge requests can be merged with skipped jobs |
1127
| `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved |
1128
| `merge_method` | string | no | Set the [merge method](#project-merge-method) used |
1129
| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch |
1130
| `suggestion_commit_message` | string | no | The commit message used to apply merge request suggestions |
1131
| `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests |
1132 1133
| `lfs_enabled` | boolean | no | Enable LFS |
| `request_access_enabled` | boolean | no | Allow users to request member access |
1134
| `tag_list`    | array   | no       | The list of tags for a project; put array of tags, that should be finally assigned to a project |
1135
| `avatar`    | mixed   | no      | Image file for avatar of the project                |
1136
| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
1137
| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` |
1138
| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) |
1139
| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled |
1140
| `build_coverage_regex` | string | no | Test coverage parsing |
1141
| `ci_config_path` | string | no | The path to CI config file |
1142 1143
| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project |
| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) |
1144
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
1145
| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge requests by default |
1146
| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project |
1147 1148
| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project |
| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds |
1149
| `initialize_with_readme` | boolean | no | `false` by default |
1150 1151 1152
| `template_name` | string | no | When used without `use_custom_template`, name of a [built-in project template](../gitlab-basics/create-project.md#built-in-templates). When used with `use_custom_template`, name of a custom project template |
| `use_custom_template` | boolean | no | **(PREMIUM)** Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template |
| `group_with_project_templates_id` | integer | no | **(PREMIUM)** For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires `use_custom_template` to be true |
Mitar's avatar
Mitar committed
1153
| `packages_enabled` | boolean | no | **(PREMIUM ONLY)** Enable or disable packages repository feature |
1154

1155
NOTE: **Note:** If your HTTP repository is not publicly accessible,
1156 1157
add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
where `password` is a public access key with the `api` scope enabled.
1158

1159
## Edit project
1160

1161
Updates an existing project.
1162

1163
```plaintext
1164 1165 1166
PUT /projects/:id
```

1167 1168
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1169
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1170
| `name` | string | no | The name of the project |
1171
| `path` | string | no | Custom repository name for the project. By default generated based on name |
1172
| `default_branch` | string | no | `master` by default |
1173
| `description` | string | no | Short project description |
1174 1175 1176 1177 1178 1179 1180 1181
| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead |
| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead |
| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead |
| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead |
| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead |
| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1182
| `forking_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1183 1184 1185
| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` |
| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` |
1186
| `pages_access_level` | string | no | One of `disabled`, `private`, `enabled` or `public` |
1187
| `emails_disabled` | boolean | no | Disable email notifications |
1188
| `show_default_award_emojis` | boolean | no | Show default award emojis |
1189
| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
1190
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
1191
| `container_expiration_policy_attributes` | hash | no | Update the image expiration policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean) |
1192
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
1193
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
1194
| `import_url` | string | no | URL to import repository from |
1195
| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members |
1196
| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs |
1197
| `allow_merge_on_skipped_pipeline` | boolean | no | Set whether or not merge requests can be merged with skipped jobs |
1198
| `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved |
1199
| `merge_method` | string | no | Set the [merge method](#project-merge-method) used |
1200
| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch |
1201
| `suggestion_commit_message` | string | no | The commit message used to apply merge request suggestions |
1202
| `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests |
1203 1204
| `lfs_enabled` | boolean | no | Enable LFS |
| `request_access_enabled` | boolean | no | Allow users to request member access |
1205
| `tag_list`    | array   | no       | The list of tags for a project; put array of tags, that should be finally assigned to a project |
1206
| `avatar`    | mixed   | no      | Image file for avatar of the project                |
1207
| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` |
1208
| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) |
1209
| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled |
1210
| `build_coverage_regex` | string | no | Test coverage parsing |
1211
| `ci_config_path` | string | no | The path to CI config file |
1212
| `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#git-shallow-clone) |
1213 1214
| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project |
| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) |
1215
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
1216
| `approvals_before_merge` | integer | no | **(STARTER)** How many approvers should approve merge request by default |
1217
| `external_authorization_classification_label` | string | no | **(PREMIUM)** The classification label for the project |
1218
| `mirror` | boolean | no | **(STARTER)** Enables pull mirroring in a project |
1219
| `mirror_user_id` | integer | no | **(STARTER)** User responsible for all the activity surrounding a pull mirror event. Can only be set by admins. |
1220 1221 1222 1223
| `mirror_trigger_builds` | boolean | no | **(STARTER)** Pull mirroring triggers builds |
| `only_mirror_protected_branches` | boolean | no | **(STARTER)** Only mirror protected branches |
| `mirror_overwrites_diverged_branches` | boolean | no | **(STARTER)** Pull mirror overwrites diverged branches |
| `packages_enabled` | boolean | no | **(PREMIUM ONLY)** Enable or disable packages repository feature |
1224
| `service_desk_enabled` | boolean | no | **(PREMIUM ONLY)** Enable or disable service desk feature |
1225

1226
NOTE: **Note:** If your HTTP repository is not publicly accessible,
1227 1228
add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
where `password` is a public access key with the `api` scope enabled.
1229

1230
## Fork project
1231

1232
Forks a project into the user namespace of the authenticated user or the one provided.
1233

1234 1235 1236
The forking operation for a project is asynchronous and is completed in a
background job. The request will return immediately. To determine whether the
fork of the project has completed, query the `import_status` for the new project.
1237

1238
```plaintext
1239
POST /projects/:id/fork
1240 1241
```

1242 1243
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1244
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1245 1246 1247
| `namespace` | integer/string | no | (deprecated) The ID or path of the namespace that the project will be forked to |
| `namespace_id` | integer | no | The ID of the namespace that the project will be forked to |
| `namespace_path` | string | no | The path of the namespace that the project will be forked to |
1248 1249
| `path` | string | no | The path that will be assigned to the resultant project after forking |
| `name` | string | no | The name that will be assigned to the resultant project after forking |
1250

1251 1252 1253 1254 1255 1256
## List Forks of a project

>**Note:** This feature was introduced in GitLab 10.1

List the projects accessible to the calling user that have an established, forked relationship with the specified project

1257
```plaintext
1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268
GET /projects/:id/forks
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `archived` | boolean | no | Limit by archived status |
| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` |
| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Return list of projects matching the search criteria |
1269
| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. |
1270
| `owned` | boolean | no | Limit by projects explicitly owned by the current user |
1271 1272 1273
| `membership` | boolean | no | Limit by projects that the current user is a member of |
| `starred` | boolean | no | Limit by projects starred by the current user |
| `statistics` | boolean | no | Include project statistics |
1274
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
1275 1276
| `with_issues_enabled` | boolean | no | Limit by enabled issues feature |
| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature |
1277
| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) |
1278

1279
```shell
1280
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks"
1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294
```

Example responses:

```json
[
  {
    "id": 3,
    "description": null,
    "default_branch": "master",
    "visibility": "internal",
    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
    "web_url": "http://example.com/diaspora/diaspora-project-site",
1295
    "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309
    "tag_list": [
      "example",
      "disapora project"
    ],
    "name": "Diaspora Project Site",
    "name_with_namespace": "Diaspora / Diaspora Project Site",
    "path": "diaspora-project-site",
    "path_with_namespace": "diaspora/diaspora-project-site",
    "issues_enabled": true,
    "open_issues_count": 1,
    "merge_requests_enabled": true,
    "jobs_enabled": true,
    "wiki_enabled": true,
    "snippets_enabled": false,
1310
    "can_create_merge_request_in": true,
1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331
    "resolve_outdated_diff_discussions": false,
    "container_registry_enabled": false,
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "creator_id": 3,
    "namespace": {
      "id": 3,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora"
    },
    "import_status": "none",
    "archived": true,
    "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
    "shared_runners_enabled": true,
    "forks_count": 0,
    "star_count": 1,
    "public_jobs": true,
    "shared_with_groups": [],
    "only_allow_merge_if_pipeline_succeeds": false,
1332
    "allow_merge_on_skipped_pipeline": false,
1333
    "only_allow_merge_if_all_discussions_are_resolved": false,
1334
    "remove_source_branch_after_merge": false,
1335
    "request_access_enabled": false,
1336
    "merge_method": "merge",
1337
    "autoclose_referenced_issues": true,
1338
    "suggestion_commit_message": null,
1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351
    "_links": {
      "self": "http://example.com/api/v4/projects",
      "issues": "http://example.com/api/v4/projects/1/issues",
      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
      "labels": "http://example.com/api/v4/projects/1/labels",
      "events": "http://example.com/api/v4/projects/1/events",
      "members": "http://example.com/api/v4/projects/1/members"
    }
  }
]
```

1352
## Star a project
1353

1354
Stars a given project. Returns status code `304` if the project is already starred.
1355

1356
```plaintext
1357 1358 1359 1360 1361
POST /projects/:id/star
```

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

1364
```shell
1365
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star"
1366 1367 1368 1369 1370 1371 1372 1373 1374
```

Example response:

```json
{
  "id": 3,
  "description": null,
  "default_branch": "master",
1375
  "visibility": "internal",
1376 1377 1378
  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
1379
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390
  "tag_list": [
    "example",
    "disapora project"
  ],
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
1391
  "jobs_enabled": true,
1392 1393
  "wiki_enabled": true,
  "snippets_enabled": false,
1394
  "can_create_merge_request_in": true,
1395
  "resolve_outdated_diff_discussions": false,
1396
  "container_registry_enabled": false,
Ben Boeckel's avatar
Ben Boeckel committed
1397 1398
  "created_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
1399 1400 1401 1402 1403
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
1404 1405
    "kind": "group",
    "full_path": "diaspora"
1406
  },
1407
  "import_status": "none",
1408 1409
  "archived": true,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
1410 1411 1412 1413 1414 1415 1416 1417
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  },
1418 1419
  "shared_runners_enabled": true,
  "forks_count": 0,
1420
  "star_count": 1,
1421
  "public_jobs": true,
1422
  "shared_with_groups": [],
1423
  "only_allow_merge_if_pipeline_succeeds": false,
1424
  "allow_merge_on_skipped_pipeline": false,
1425
  "only_allow_merge_if_all_discussions_are_resolved": false,
1426
  "remove_source_branch_after_merge": false,
1427
  "request_access_enabled": false,
1428
  "merge_method": "merge",
1429
  "autoclose_referenced_issues": true,
1430
  "suggestion_commit_message": null,
1431 1432 1433 1434 1435 1436 1437 1438 1439
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members"
  }
1440 1441 1442
}
```

1443
## Unstar a project
1444

1445
Unstars a given project. Returns status code `304` if the project is not starred.
1446

1447
```plaintext
1448
POST /projects/:id/unstar
1449 1450 1451 1452
```

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

1455
```shell
1456
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar"
1457 1458 1459 1460 1461 1462 1463 1464 1465
```

Example response:

```json
{
  "id": 3,
  "description": null,
  "default_branch": "master",
1466
  "visibility": "internal",
1467 1468 1469
  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
1470
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481
  "tag_list": [
    "example",
    "disapora project"
  ],
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
1482
  "jobs_enabled": true,
1483 1484
  "wiki_enabled": true,
  "snippets_enabled": false,
1485
  "can_create_merge_request_in": true,
1486
  "resolve_outdated_diff_discussions": false,
1487
  "container_registry_enabled": false,
Ben Boeckel's avatar
Ben Boeckel committed
1488 1489
  "created_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
1490 1491 1492 1493 1494
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
1495 1496
    "kind": "group",
    "full_path": "diaspora"
1497
  },
1498
  "import_status": "none",
1499 1500
  "archived": true,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
1501 1502 1503 1504 1505 1506 1507 1508
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  },
1509 1510
  "shared_runners_enabled": true,
  "forks_count": 0,
1511
  "star_count": 0,
1512
  "public_jobs": true,
1513
  "shared_with_groups": [],
1514
  "only_allow_merge_if_pipeline_succeeds": false,
1515
  "allow_merge_on_skipped_pipeline": false,
1516
  "only_allow_merge_if_all_discussions_are_resolved": false,
1517
  "remove_source_branch_after_merge": false,
1518
  "request_access_enabled": false,
1519
  "merge_method": "merge",
1520
  "autoclose_referenced_issues": true,
1521
  "suggestion_commit_message": null,
1522 1523 1524 1525 1526 1527 1528 1529 1530
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members"
  }
1531 1532 1533
}
```

1534 1535
## List Starrers of a project

Camil Staps's avatar
Camil Staps committed
1536
List the users who starred the specified project.
1537

1538
```plaintext
1539 1540 1541 1542 1543
GET /projects/:id/starrers
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1544
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
Camil Staps's avatar
Camil Staps committed
1545
| `search` | string | no | Search for specific users. |
1546

1547
```shell
1548 1549 1550 1551 1552 1553 1554 1555
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/starrers"
```

Example responses:

```json
[
  {
1556 1557 1558 1559 1560 1561 1562 1563 1564 1565
    "starred_since": "2019-01-28T14:47:30.642Z",
    "user":
      {
        "id": 1,
        "username": "jane_smith",
        "name": "Jane Smith",
        "state": "active",
        "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
        "web_url": "http://localhost:3000/jane_smith"
      }
1566
  },
1567 1568 1569 1570 1571 1572 1573 1574 1575 1576
    "starred_since": "2018-01-02T11:40:26.570Z",
    "user":
      {
        "id": 2,
        "username": "janine_smith",
        "name": "Janine Smith",
        "state": "blocked",
        "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
        "web_url": "http://localhost:3000/janine_smith"
      }
1577 1578 1579
]
```

1580 1581 1582 1583
## Languages

Get languages used in a project with percentage value.

1584
```plaintext
1585 1586 1587
GET /projects/:id/languages
```

1588 1589 1590 1591
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |

1592
```shell
1593
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages"
1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606
```

Example response:

```json
{
  "Ruby": 66.69,
  "JavaScript": 22.98,
  "HTML": 7.91,
  "CoffeeScript": 2.42
}
```

1607
## Archive a project
1608

1609
Archives the project if the user is either admin or the project owner of this project. This action is
1610 1611
idempotent, thus archiving an already archived project will not change the project.

1612
```plaintext
1613
POST /projects/:id/archive
1614 1615 1616 1617
```

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

1620
```shell
1621
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive"
1622 1623 1624 1625 1626 1627 1628 1629 1630
```

Example response:

```json
{
  "id": 3,
  "description": null,
  "default_branch": "master",
1631
  "visibility": "private",
1632 1633 1634
  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
1635
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
1636 1637 1638 1639 1640 1641 1642
  "tag_list": [
    "example",
    "disapora project"
  ],
  "owner": {
    "id": 3,
    "name": "Diaspora",
Ben Boeckel's avatar
Ben Boeckel committed
1643
    "created_at": "2013-09-30T13:46:02Z"
1644 1645 1646 1647 1648 1649 1650 1651
  },
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
1652
  "jobs_enabled": true,
1653 1654
  "wiki_enabled": true,
  "snippets_enabled": false,
1655
  "can_create_merge_request_in": true,
1656
  "resolve_outdated_diff_discussions": false,
1657
  "container_registry_enabled": false,
Ben Boeckel's avatar
Ben Boeckel committed
1658 1659
  "created_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
1660 1661 1662 1663 1664
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
1665 1666
    "kind": "group",
    "full_path": "diaspora"
1667
  },
1668 1669
  "import_status": "none",
  "import_error": null,
1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681
  "permissions": {
    "project_access": {
      "access_level": 10,
      "notification_level": 3
    },
    "group_access": {
      "access_level": 50,
      "notification_level": 3
    }
  },
  "archived": true,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
1682 1683 1684 1685 1686 1687 1688 1689
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  },
1690 1691 1692
  "shared_runners_enabled": true,
  "forks_count": 0,
  "star_count": 0,
1693
  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
1694
  "ci_default_git_depth": 50,
1695
  "public_jobs": true,
1696
  "shared_with_groups": [],
1697
  "only_allow_merge_if_pipeline_succeeds": false,
1698
  "allow_merge_on_skipped_pipeline": false,
1699
  "only_allow_merge_if_all_discussions_are_resolved": false,
1700
  "remove_source_branch_after_merge": false,
1701
  "request_access_enabled": false,
1702
  "merge_method": "merge",
1703
  "autoclose_referenced_issues": true,
1704
  "suggestion_commit_message": null,
1705 1706 1707 1708 1709 1710 1711 1712 1713
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members"
  }
1714 1715 1716
}
```

1717
## Unarchive a project
1718

1719
Unarchives the project if the user is either admin or the project owner of this project. This action is
Ville Skyttä's avatar
Ville Skyttä committed
1720
idempotent, thus unarchiving a non-archived project will not change the project.
1721

1722
```plaintext
Sergey Gnuskov's avatar
Sergey Gnuskov committed
1723
POST /projects/:id/unarchive
1724 1725 1726 1727
```

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

1730
```shell
1731
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive"
1732 1733 1734 1735 1736 1737 1738 1739 1740
```

Example response:

```json
{
  "id": 3,
  "description": null,
  "default_branch": "master",
1741
  "visibility": "private",
1742 1743 1744
  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
1745
  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md",
1746 1747 1748 1749 1750 1751 1752
  "tag_list": [
    "example",
    "disapora project"
  ],
  "owner": {
    "id": 3,
    "name": "Diaspora",
Ben Boeckel's avatar
Ben Boeckel committed
1753
    "created_at": "2013-09-30T13:46:02Z"
1754 1755 1756 1757 1758 1759 1760 1761
  },
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
  "issues_enabled": true,
  "open_issues_count": 1,
  "merge_requests_enabled": true,
1762
  "jobs_enabled": true,
1763 1764
  "wiki_enabled": true,
  "snippets_enabled": false,
1765
  "can_create_merge_request_in": true,
1766
  "resolve_outdated_diff_discussions": false,
1767
  "container_registry_enabled": false,
Ben Boeckel's avatar
Ben Boeckel committed
1768 1769
  "created_at": "2013-09-30T13:46:02Z",
  "last_activity_at": "2013-09-30T13:46:02Z",
1770 1771 1772 1773 1774
  "creator_id": 3,
  "namespace": {
    "id": 3,
    "name": "Diaspora",
    "path": "diaspora",
1775 1776
    "kind": "group",
    "full_path": "diaspora"
1777
  },
1778 1779
  "import_status": "none",
  "import_error": null,
1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791
  "permissions": {
    "project_access": {
      "access_level": 10,
      "notification_level": 3
    },
    "group_access": {
      "access_level": 50,
      "notification_level": 3
    }
  },
  "archived": false,
  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
1792 1793 1794 1795 1796 1797 1798 1799
  "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE",
  "license": {
    "key": "lgpl-3.0",
    "name": "GNU Lesser General Public License v3.0",
    "nickname": "GNU LGPLv3",
    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
  },
1800 1801 1802
  "shared_runners_enabled": true,
  "forks_count": 0,
  "star_count": 0,
1803
  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
1804
  "ci_default_git_depth": 50,
1805
  "public_jobs": true,
1806
  "shared_with_groups": [],
1807
  "only_allow_merge_if_pipeline_succeeds": false,
1808
  "allow_merge_on_skipped_pipeline": false,
1809
  "only_allow_merge_if_all_discussions_are_resolved": false,
1810
  "remove_source_branch_after_merge": false,
1811
  "request_access_enabled": false,
1812
  "merge_method": "merge",
1813
  "autoclose_referenced_issues": true,
1814
  "suggestion_commit_message": null,
1815 1816 1817 1818 1819 1820 1821 1822 1823
  "_links": {
    "self": "http://example.com/api/v4/projects",
    "issues": "http://example.com/api/v4/projects/1/issues",
    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
    "labels": "http://example.com/api/v4/projects/1/labels",
    "events": "http://example.com/api/v4/projects/1/events",
    "members": "http://example.com/api/v4/projects/1/members"
  }
1824 1825 1826
}
```

1827
## Remove project
1828

Gosia Ksionek's avatar
Gosia Ksionek committed
1829 1830 1831
This endpoint either:

- Removes a project including all associated resources (issues, merge requests etc).
1832
- From [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a project for deletion. Actual
Gosia Ksionek's avatar
Gosia Ksionek committed
1833
  deletion happens after number of days specified in
1834
  [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only).
1835

1836
```plaintext
1837 1838 1839
DELETE /projects/:id
```

1840 1841
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1842
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1843

Gosia Ksionek's avatar
Gosia Ksionek committed
1844 1845
## Restore project marked for deletion **(PREMIUM)**

1846
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6.
1847

Gosia Ksionek's avatar
Gosia Ksionek committed
1848 1849
Restores project marked for deletion.

1850
```plaintext
Gosia Ksionek's avatar
Gosia Ksionek committed
1851 1852 1853 1854 1855 1856 1857
POST /projects/:id/restore
```

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

1858
## Upload a file
1859 1860 1861

Uploads a file to the specified project to be used in an issue or merge request description, or a comment.

1862
```plaintext
1863 1864 1865
POST /projects/:id/uploads
```

1866 1867
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1868
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1869
| `file` | string | yes | The file to be uploaded |
1870

1871 1872 1873 1874 1875
To upload a file from your filesystem, 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 filesystem and be preceded
by `@`. For example:

1876
```shell
Greg Myers's avatar
Greg Myers committed
1877
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/5/uploads"
1878 1879 1880 1881
```

Returned object:

1882 1883 1884 1885
```json
{
  "alt": "dk",
  "url": "/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
1886
  "full_path": "/namespace1/project1/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
1887 1888 1889 1890
  "markdown": "![dk](/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png)"
}
```

1891
>**Note**: The returned `url` is relative to the project path. The returned `full_path` is the absolute path to the file.
1892 1893
In Markdown contexts, the link is automatically expanded when the format in
`markdown` is used.
1894

1895
## Share project with group
1896 1897 1898

Allow to share project with group.

1899
```plaintext
1900 1901 1902
POST /projects/:id/share
```

1903 1904
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1905
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1906
| `group_id` | integer | yes | The ID of the group to share with |
1907
| `group_access` | integer | yes | The [permissions level](members.md) to grant the group |
1908
| `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 |
1909

1910
## Delete a shared project link within a group
1911 1912 1913

Unshare the project from the group. Returns `204` and no content on success.

1914
```plaintext
1915 1916 1917 1918 1919
DELETE /projects/:id/share/:group_id
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1920
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1921 1922
| `group_id` | integer | yes | The ID of the group |

1923
```shell
Greg Myers's avatar
Greg Myers committed
1924
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17"
1925 1926
```

1927 1928
## Hooks

1929 1930 1931
Also called Project Hooks and Webhooks.
These are different for [System Hooks](system_hooks.md) that are system wide.

1932 1933
### List project hooks

1934
Get a list of project hooks.
miks's avatar
miks committed
1935

1936
```plaintext
miks's avatar
miks committed
1937 1938 1939
GET /projects/:id/hooks
```

1940 1941
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1942
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
miks's avatar
miks committed
1943

1944
### Get project hook
1945

1946
Get a specific hook for a project.
1947

1948
```plaintext
1949 1950 1951
GET /projects/:id/hooks/:hook_id
```

1952 1953
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1954
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1955
| `hook_id` | integer | yes | The ID of a project hook |
1956

1957 1958 1959 1960
```json
{
  "id": 1,
  "url": "http://example.com/hook",
1961
  "project_id": 3,
Ben Boeckel's avatar
Ben Boeckel committed
1962
  "push_events": true,
1963
  "push_events_branch_filter": "",
Ben Boeckel's avatar
Ben Boeckel committed
1964
  "issues_events": true,
1965
  "confidential_issues_events": true,
Ben Boeckel's avatar
Ben Boeckel committed
1966
  "merge_requests_events": true,
1967
  "tag_push_events": true,
Ben Boeckel's avatar
Ben Boeckel committed
1968
  "note_events": true,
1969
  "confidential_note_events": true,
1970
  "job_events": true,
1971
  "pipeline_events": true,
1972
  "wiki_page_events": true,
Ben Boeckel's avatar
Ben Boeckel committed
1973
  "enable_ssl_verification": true,
1974 1975 1976 1977 1978 1979
  "created_at": "2012-10-12T17:04:47Z"
}
```

### Add project hook

1980
Adds a hook to a specified project.
miks's avatar
miks committed
1981

1982
```plaintext
miks's avatar
miks committed
1983 1984 1985
POST /projects/:id/hooks
```

1986 1987
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1988
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
1989 1990
| `url` | string | yes | The hook URL |
| `push_events` | boolean | no | Trigger hook on push events |
1991
| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only |
1992
| `issues_events` | boolean | no | Trigger hook on issues events |
1993
| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events |
1994 1995 1996
| `merge_requests_events` | boolean | no | Trigger hook on merge requests events |
| `tag_push_events` | boolean | no | Trigger hook on tag push events |
| `note_events` | boolean | no | Trigger hook on note events |
1997
| `confidential_note_events` | boolean | no | Trigger hook on confidential note events |
1998
| `job_events` | boolean | no | Trigger hook on job events |
1999
| `pipeline_events` | boolean | no | Trigger hook on pipeline events |
2000
| `wiki_page_events` | boolean | no | Trigger hook on wiki events |
2001
| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook |
2002
| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response |
2003

2004 2005
### Edit project hook

2006
Edits a hook for a specified project.
2007

2008
```plaintext
2009 2010 2011
PUT /projects/:id/hooks/:hook_id
```

2012 2013
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2014
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
2015 2016 2017
| `hook_id` | integer | yes | The ID of the project hook |
| `url` | string | yes | The hook URL |
| `push_events` | boolean | no | Trigger hook on push events |
2018
| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only |
2019
| `issues_events` | boolean | no | Trigger hook on issues events |
2020
| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events |
2021 2022 2023
| `merge_requests_events` | boolean | no | Trigger hook on merge requests events |
| `tag_push_events` | boolean | no | Trigger hook on tag push events |
| `note_events` | boolean | no | Trigger hook on note events |
2024
| `confidential_note_events` | boolean | no | Trigger hook on confidential note events |
2025
| `job_events` | boolean | no | Trigger hook on job events |
2026 2027 2028
| `pipeline_events` | boolean | no | Trigger hook on pipeline events |
| `wiki_events` | boolean | no | Trigger hook on wiki events |
| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook |
2029
| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response |
2030

2031
### Delete project hook
miks's avatar
miks committed
2032

2033
Removes a hook from a project. This is an idempotent method and can be called multiple times.
2034
Either the hook is available or not.
miks's avatar
miks committed
2035

2036
```plaintext
2037
DELETE /projects/:id/hooks/:hook_id
miks's avatar
miks committed
2038 2039
```

2040 2041
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2042
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
2043
| `hook_id` | integer | yes | The ID of the project hook |
miks's avatar
miks committed
2044

2045 2046
Note the JSON response differs if the hook is available or not. If the project hook
is available before it is returned in the JSON response or an empty response is returned.
2047

2048
## Fork relationship
2049

2050
Allows modification of the forked relationship between existing projects. Available only for project owners and admins.
2051

2052
### Create a forked from/to relation between existing projects
2053

2054
```plaintext
2055 2056 2057
POST /projects/:id/fork/:forked_from_id
```

2058 2059
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2060
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
2061
| `forked_from_id` | ID | yes | The ID of the project that was forked from |
2062 2063 2064

### Delete an existing forked from relationship

2065
```plaintext
2066 2067 2068
DELETE /projects/:id/fork
```

2069 2070
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2071
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
2072 2073 2074

## Search for projects by name

2075 2076 2077
Search for projects by name which are accessible to the authenticated user. This
endpoint can be accessed without authentication if the project is publicly
accessible.
2078

2079
```plaintext
2080
GET /projects
2081 2082
```

2083 2084
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2085
| `search` | string | yes | A string contained in the project name |
2086
| `order_by` | string | no | Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields |
2087
| `sort` | string | no | Return requests sorted in `asc` or `desc` order |
2088

2089
```shell
Greg Myers's avatar
Greg Myers committed
2090
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test"
2091 2092
```

2093 2094
## Start the Housekeeping task for a Project

2095
> Introduced in GitLab 9.0.
2096

2097
```plaintext
2098 2099 2100
POST /projects/:id/housekeeping
```

2101 2102 2103 2104
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |

2105
## Push Rules **(STARTER)**
2106 2107 2108 2109 2110

### Get project push rules

Get the push rules of a project.

2111
```plaintext
2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123
GET /projects/:id/push_rule
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |

```json
{
  "id": 1,
  "project_id": 3,
  "commit_message_regex": "Fixes \d+\..*",
2124
  "commit_message_negative_regex": "ssh\:\/\/",
2125 2126 2127 2128 2129 2130 2131 2132
  "branch_name_regex": "",
  "deny_delete_tag": false,
  "created_at": "2012-10-12T17:04:47Z",
  "member_check": false,
  "prevent_secrets": false,
  "author_email_regex": "",
  "file_name_regex": "",
  "max_file_size": 5,
2133 2134
  "commit_committer_check": false,
  "reject_unsigned_commits": false
2135 2136 2137
}
```

2138
Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will also see
2139
the `commit_committer_check` and `reject_unsigned_commits` parameters:
2140

2141 2142 2143 2144
```json
{
  "id": 1,
  "project_id": 3,
2145 2146
  "commit_committer_check": false,
  "reject_unsigned_commits": false
2147 2148 2149
  ...
}
```
2150 2151 2152 2153 2154

### Add project push rule

Adds a push rule to a specified project.

2155
```plaintext
2156 2157 2158
POST /projects/:id/push_rule
```

2159 2160 2161 2162 2163 2164 2165 2166 2167 2168
| Attribute                                     | Type           | Required | Description |
| --------------------------------------------- | -------------- | -------- | ----------- |
| `id`                                          | integer/string | yes      | The ID of the project or NAMESPACE/PROJECT_NAME |
| `deny_delete_tag` **(STARTER)**               | boolean        | no       | Deny deleting a tag |
| `member_check` **(STARTER)**                  | boolean        | no       | Restrict commits by author (email) to existing GitLab users |
| `prevent_secrets` **(STARTER)**               | boolean        | no       | GitLab will reject any files that are likely to contain secrets |
| `commit_message_regex` **(STARTER)**          | string         | no       | All commit messages must match this, e.g. `Fixed \d+\..*` |
| `commit_message_negative_regex` **(STARTER)** | string         | no       | No commit message is allowed to match this, e.g. `ssh\:\/\/` |
| `branch_name_regex` **(STARTER)**             | string         | no       | All branch names must match this, e.g. `(feature|hotfix)\/*` |
| `author_email_regex` **(STARTER)**            | string         | no       | All commit author emails must match this, e.g. `@my-company.com$` |
2169
| `file_name_regex` **(STARTER)**               | string         | no       | All committed filenames must **not** match this, e.g. `(jar|exe)$` |
2170 2171
| `max_file_size` **(STARTER)**                 | integer        | no       | Maximum file size (MB) |
| `commit_committer_check` **(PREMIUM)**        | boolean        | no       | Users can only push commits to this repository that were committed with one of their own verified emails. |
2172
| `reject_unsigned_commits` **(PREMIUM)**        | boolean        | no       | Reject commit when it is not signed through GPG. |
2173 2174 2175 2176 2177

### Edit project push rule

Edits a push rule for a specified project.

2178
```plaintext
2179 2180 2181
PUT /projects/:id/push_rule
```

2182 2183 2184 2185 2186 2187 2188 2189 2190 2191
| Attribute                                     | Type           | Required | Description |
| --------------------------------------------- | -------------- | -------- | ----------- |
| `id`                                          | integer/string | yes      | The ID of the project or NAMESPACE/PROJECT_NAME |
| `deny_delete_tag` **(STARTER)**               | boolean        | no       | Deny deleting a tag |
| `member_check` **(STARTER)**                  | boolean        | no       | Restrict commits by author (email) to existing GitLab users |
| `prevent_secrets` **(STARTER)**               | boolean        | no       | GitLab will reject any files that are likely to contain secrets |
| `commit_message_regex` **(STARTER)**          | string         | no       | All commit messages must match this, e.g. `Fixed \d+\..*` |
| `commit_message_negative_regex` **(STARTER)** | string         | no       | No commit message is allowed to match this, e.g. `ssh\:\/\/` |
| `branch_name_regex` **(STARTER)**             | string         | no       | All branch names must match this, e.g. `(feature|hotfix)\/*` |
| `author_email_regex` **(STARTER)**            | string         | no       | All commit author emails must match this, e.g. `@my-company.com$` |
2192
| `file_name_regex` **(STARTER)**               | string         | no       | All committed filenames must **not** match this, e.g. `(jar|exe)$` |
2193 2194
| `max_file_size` **(STARTER)**                 | integer        | no       | Maximum file size (MB) |
| `commit_committer_check` **(PREMIUM)**        | boolean        | no       | Users can only push commits to this repository that were committed with one of their own verified emails. |
2195
| `reject_unsigned_commits` **(PREMIUM)**        | boolean        | no       | Reject commits when they are not GPG signed. |
2196 2197 2198 2199 2200 2201 2202 2203

### Delete project push rule

> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0.

Removes a push rule from a project. This is an idempotent method and can be called multiple times.
Either the push rule is available or not.

2204
```plaintext
2205 2206 2207
DELETE /projects/:id/push_rule
```

2208 2209
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2210 2211
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |

2212 2213 2214
## Transfer a project to a new namespace

> Introduced in GitLab 11.1.
2215

2216
```plaintext
2217 2218 2219 2220 2221
PUT /projects/:id/transfer
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2222
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
2223 2224
| `namespace` | integer/string | yes | The ID or path of the namespace to transfer to project to |

2225 2226 2227 2228
## Branches

Read more in the [Branches](branches.md) documentation.

James Lopez's avatar
James Lopez committed
2229 2230
## Project Import/Export

James Lopez's avatar
James Lopez committed
2231
Read more in the [Project import/export](project_import_export.md) documentation.
James Lopez's avatar
James Lopez committed
2232

2233 2234 2235
## Project members

Read more in the [Project members](members.md) documentation.
2236

2237
## Start the pull mirroring process for a Project **(STARTER)**
2238

2239
> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
2240

2241
```plaintext
2242 2243 2244 2245 2246 2247 2248
POST /projects/:id/mirror/pull
```

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

2249
```shell
Greg Myers's avatar
Greg Myers committed
2250
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"
2251 2252
```

2253 2254 2255
## Project badges

Read more in the [Project Badges](project_badges.md) documentation.
2256 2257 2258

## Issue and merge request description templates

2259 2260
The non-default [issue and merge request description templates](../user/project/description_templates.md) are managed inside the project's repository. So you can manage them via the API through the [Repositories API](repositories.md) and the [Repository Files API](repository_files.md).

2261
## Download snapshot of a Git repository
2262 2263 2264 2265 2266

> Introduced in GitLab 10.7

This endpoint may only be accessed by an administrative user.

2267
Download a snapshot of the project (or wiki, if requested) Git repository. This
2268 2269 2270 2271 2272 2273
snapshot is always in uncompressed [tar](https://en.wikipedia.org/wiki/Tar_(computing))
format.

If a repository is corrupted to the point where `git clone` does not work, the
snapshot may allow some of the data to be retrieved.

2274
```plaintext
2275 2276 2277 2278 2279 2280 2281
GET /projects/:id/snapshot
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `wiki`    | boolean | no | Whether to download the wiki, rather than project, repository |