projects.md 13.3 KB
Newer Older
1 2 3
## Projects

### List projects
Nihad Abbasov's avatar
Nihad Abbasov committed
4

5
Get a list of projects accessible by the authenticated user.
Nihad Abbasov's avatar
Nihad Abbasov committed
6 7 8 9 10 11 12 13

```
GET /projects
```

```json
[
  {
Marin Jankovski's avatar
Marin Jankovski committed
14
    "id": 4,
Nihad Abbasov's avatar
Nihad Abbasov committed
15 16
    "description": null,
    "default_branch": "master",
Marin Jankovski's avatar
Marin Jankovski committed
17
    "public": false,
18
    "visibility_level": 0,
Marin Jankovski's avatar
Marin Jankovski committed
19 20 21
    "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",
Nihad Abbasov's avatar
Nihad Abbasov committed
22
    "owner": {
Marin Jankovski's avatar
Marin Jankovski committed
23 24 25
      "id": 3,
      "name": "Diaspora",
      "created_at": "2013-09-30T13: 46: 02Z"
Nihad Abbasov's avatar
Nihad Abbasov committed
26
    },
Marin Jankovski's avatar
Marin Jankovski committed
27 28 29 30 31 32 33
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wall_enabled": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
34
    "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
35 36 37 38 39 40 41 42 43 44 45 46
    "snippets_enabled": false,
    "created_at": "2013-09-30T13: 46: 02Z",
    "last_activity_at": "2013-09-30T13: 46: 02Z",
    "namespace": {
      "created_at": "2013-09-30T13: 46: 02Z",
      "description": "",
      "id": 3,
      "name": "Diaspora",
      "owner_id": 1,
      "path": "diaspora",
      "updated_at": "2013-09-30T13: 46: 02Z"
    }
Nihad Abbasov's avatar
Nihad Abbasov committed
47 48
  },
  {
Marin Jankovski's avatar
Marin Jankovski committed
49
    "id": 6,
Nihad Abbasov's avatar
Nihad Abbasov committed
50
    "description": null,
Marin Jankovski's avatar
Marin Jankovski committed
51 52
    "default_branch": "master",
    "public": false,
53
    "visibility_level": 0,
Marin Jankovski's avatar
Marin Jankovski committed
54 55 56 57 58 59 60
    "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",
    "owner":  {
      "id": 4,
      "name": "Brightbox",
      "created_at": "2013-09-30T13:46:02Z"
Nihad Abbasov's avatar
Nihad Abbasov committed
61
    },
Marin Jankovski's avatar
Marin Jankovski committed
62 63 64 65
    "name": "Puppet",
    "name_with_namespace": "Brightbox / Puppet",
    "path": "puppet",
    "path_with_namespace": "brightbox/puppet",
Nihad Abbasov's avatar
Nihad Abbasov committed
66 67
    "issues_enabled": true,
    "merge_requests_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
68
    "wall_enabled": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
69
    "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
70 71 72 73 74 75 76 77 78 79 80 81
    "snippets_enabled": false,
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "namespace":  {
      "created_at": "2013-09-30T13:46:02Z",
      "description": "",
      "id": 4,
      "name": "Brightbox",
      "owner_id": 1,
      "path": "brightbox",
      "updated_at": "2013-09-30T13:46:02Z"
    }
Nihad Abbasov's avatar
Nihad Abbasov committed
82 83 84 85
  }
]
```

86

87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
#### List owned projects

Get a list of projects owned by the authenticated user.

```
GET /projects/owned
```

#### List ALL projects

Get a list of all GitLab projects (admin only).

```
GET /projects/all
```

103
### Get single project
Nihad Abbasov's avatar
Nihad Abbasov committed
104

Marin Jankovski's avatar
Marin Jankovski committed
105 106
Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME , which is owned by the authentication user.
If using namespaced projects call make sure that the NAMESPACE/PROJECT_NAME is URL-encoded, eg. `/api/v3/projects/diaspora%2Fdiaspora` (where `/` is represented by `%2F`).
Nihad Abbasov's avatar
Nihad Abbasov committed
107 108 109 110 111 112 113

```
GET /projects/:id
```

Parameters:

Marin Jankovski's avatar
Marin Jankovski committed
114
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
Nihad Abbasov's avatar
Nihad Abbasov committed
115

116 117
```json
{
Marin Jankovski's avatar
Marin Jankovski committed
118
  "id": 3,
119
  "description": null,
Marin Jankovski's avatar
Marin Jankovski committed
120 121
  "default_branch": "master",
  "public": false,
122
  "visibility_level": 0,
Marin Jankovski's avatar
Marin Jankovski committed
123 124 125
  "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",
126
  "owner": {
Marin Jankovski's avatar
Marin Jankovski committed
127 128 129
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13: 46: 02Z"
130
  },
Marin Jankovski's avatar
Marin Jankovski committed
131 132 133 134
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
135 136
  "issues_enabled": true,
  "merge_requests_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
137
  "wall_enabled": false,
138
  "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
139 140 141 142 143 144 145 146 147 148 149 150
  "snippets_enabled": false,
  "created_at": "2013-09-30T13: 46: 02Z",
  "last_activity_at": "2013-09-30T13: 46: 02Z",
  "namespace": {
    "created_at": "2013-09-30T13: 46: 02Z",
    "description": "",
    "id": 3,
    "name": "Diaspora",
    "owner_id": 1,
    "path": "diaspora",
    "updated_at": "2013-09-30T13: 46: 02Z"
  }
151 152 153
}
```

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
### Get project events

Get a project events for specific project.
Sorted from newest to latest

```
GET /projects/:id/events
```

Parameters:

+ `id` (required) - The ID or NAME of a project

```json

[{
  "title": null,
  "project_id": 15,
  "action_name": "closed",
  "target_id": 830,
  "target_type": "Issue",
  "author_id": 1,
  "data": null,
  "target_title": "Public project search field"
}, {
  "title": null,
  "project_id": 15,
  "action_name": "opened",
  "target_id": null,
  "target_type": null,
  "author_id": 1,
  "data": {
    "before": "50d4420237a9de7be1304607147aec22e4a14af7",
    "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
    "ref": "refs/heads/master",
    "user_id": 1,
    "user_name": "Dmitriy Zaporozhets",
    "repository": {
      "name": "gitlabhq",
      "url": "git@dev.gitlab.org:gitlab/gitlabhq.git",
      "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.",
      "homepage": "https://dev.gitlab.org/gitlab/gitlabhq"
    },
    "commits": [{
      "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
      "message": "Add simple search to projects in public area",
      "timestamp": "2013-05-13T18:18:08+00:00",
      "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428",
      "author": {
        "name": "Dmitriy Zaporozhets",
        "email": "dmitriy.zaporozhets@gmail.com"
      }
    }],
    "total_commits_count": 1
  },
  "target_title": null
}, {
  "title": null,
  "project_id": 15,
  "action_name": "closed",
  "target_id": 840,
  "target_type": "Issue",
  "author_id": 1,
  "data": null,
  "target_title": "Finish & merge Code search PR"
}]
```

222 223

### Create project
224

225
Creates new project owned by user.
226 227 228 229 230 231 232 233

```
POST /projects
```

Parameters:

+ `name` (required) - new project name
234
+ `description` (optional) - short project description
235 236 237 238 239
+ `issues_enabled` (optional)
+ `wall_enabled` (optional)
+ `merge_requests_enabled` (optional)
+ `wiki_enabled` (optional) 
+ `snippets_enabled` (optional)
240 241
+ `public` (optional) - if `true` same as setting visibility_level = 20
+ `visibility_level` (optional)
Maxime Brugidou's avatar
Maxime Brugidou committed
242
* `import_url` (optional)
243

244

245 246 247
### Create project for user

Creates a new project owned by user. Available only for admins.
248 249 250 251 252 253 254 255 256 257 258

```
POST /projects/user/:user_id
```

Parameters:

+ `user_id` (required) - user_id of owner
+ `name` (required) - new project name
+ `description` (optional) - short project description
+ `default_branch` (optional) - 'master' by default
259 260 261 262 263
+ `issues_enabled` (optional)
+ `wall_enabled` (optional)
+ `merge_requests_enabled` (optional)
+ `wiki_enabled` (optional) 
+ `snippets_enabled` (optional)
264 265
+ `public` (optional) - if `true` same as setting visibility_level = 20
+ `visibility_level` (optional)
266

267

268 269 270 271 272 273 274 275 276 277 278 279
## Remove project

Removes project with all resources(issues, merge requests etc)

```
DELETE /projects/:id
```

Parameters:

+ `id` (required) - The ID of a project

280 281 282 283

## Team members

### List project team members
miks's avatar
miks committed
284

285
Get a list of project team members.
miks's avatar
miks committed
286 287

```
288
GET /projects/:id/members
miks's avatar
miks committed
289 290 291 292
```

Parameters:

293
+ `id` (required) - The ID or NAME of a project
294
+ `query` (optional) - Query string to search for members
295 296 297


### Get project team member
miks's avatar
miks committed
298

299
Gets a project team member.
300

301 302 303 304 305
```
GET /projects/:id/members/:user_id
```

Parameters:
306

307
+ `id` (required) - The ID or NAME of a project
308 309 310 311 312
+ `user_id` (required) - The ID of a user

```json
{
  "id": 1,
313
  "username": "john_smith",
314 315
  "email": "john@example.com",
  "name": "John Smith",
Marin Jankovski's avatar
Marin Jankovski committed
316
  "state": "active",
317 318 319
  "created_at": "2012-05-23T08:00:58Z",
  "access_level": 40
}
320
```
321

322 323

### Add project team member
324

325 326
Adds a user to a project team. This is an idempotent method and can be called multiple times
with the same parameters. Adding team membership to a user that is already a member does not
327
affect the existing membership.
328 329 330

```
POST /projects/:id/members
331 332 333 334
```

Parameters:

335
+ `id` (required) - The ID or NAME of a project
336 337
+ `user_id` (required) - The ID of a user to add
+ `access_level` (required) - Project access level
338

339 340

### Edit project team member
miks's avatar
miks committed
341

342
Updates project team member to a specified access level.
miks's avatar
miks committed
343 344

```
345
PUT /projects/:id/members/:user_id
miks's avatar
miks committed
346 347 348 349
```

Parameters:

350
+ `id` (required) - The ID or NAME of a project
351 352
+ `user_id` (required) - The ID of a team member
+ `access_level` (required) - Project access level
miks's avatar
miks committed
353

354 355

### Remove project team member
miks's avatar
miks committed
356

357
Removes user from project team.
miks's avatar
miks committed
358 359

```
360
DELETE /projects/:id/members/:user_id
miks's avatar
miks committed
361 362 363 364
```

Parameters:

365
+ `id` (required) - The ID or NAME of a project
366
+ `user_id` (required) - The ID of a team member
miks's avatar
miks committed
367

368 369 370
This method is idempotent and can be called multiple times with the same parameters.
Revoking team membership for a user who is not currently a team member is considered success.
Please note that the returned JSON currently differs slightly. Thus you should not
371
rely on the returned JSON structure.
Nihad Abbasov's avatar
Nihad Abbasov committed
372

miks's avatar
miks committed
373

374 375 376 377 378
## Hooks

### List project hooks

Get list of project hooks.
miks's avatar
miks committed
379 380 381 382 383 384 385

```
GET /projects/:id/hooks
```

Parameters:

386
+ `id` (required) - The ID or NAME of a project
miks's avatar
miks committed
387 388


389
### Get project hook
390

391
Get a specific hook for project.
392 393 394 395 396

```
GET /projects/:id/hooks/:hook_id
```

397
Parameters:
398

399
+ `id` (required) - The ID or NAME of a project
400 401
+ `hook_id` (required) - The ID of a project hook

402 403 404 405
```json
{
  "id": 1,
  "url": "http://example.com/hook",
406 407 408 409
  "project_id": 3,
  "push_events": "true",
  "issues_events": "true",
  "merge_requests_events": "true",
410 411 412 413
  "created_at": "2012-10-12T17:04:47Z"
}
```

miks's avatar
miks committed
414

415 416 417
### Add project hook

Adds a hook to project.
miks's avatar
miks committed
418 419 420 421 422 423 424

```
POST /projects/:id/hooks
```

Parameters:

425
+ `id` (required) - The ID or NAME of a project
miks's avatar
miks committed
426
+ `url` (required) - The hook URL
427 428 429
+ `push_events` - Trigger hook on push events
+ `issues_events` - Trigger hook on issues events
+ `merge_requests_events` - Trigger hook on merge_requests events
miks's avatar
miks committed
430

431

432 433 434
### Edit project hook

Edits a hook for project.
435 436 437 438 439 440 441

```
PUT /projects/:id/hooks/:hook_id
```

Parameters:

442
+ `id` (required) - The ID or NAME of a project
443 444
+ `hook_id` (required) - The ID of a project hook
+ `url` (required) - The hook URL
445 446 447
+ `push_events` - Trigger hook on push events
+ `issues_events` - Trigger hook on issues events
+ `merge_requests_events` - Trigger hook on merge_requests events
448 449


450
### Delete project hook
miks's avatar
miks committed
451

452 453
Removes a hook from project. This is an idempotent method and can be called multiple times.
Either the hook is available or not.
miks's avatar
miks committed
454 455

```
456
DELETE /projects/:id/hooks/:hook_id
miks's avatar
miks committed
457 458 459 460
```

Parameters:

461
+ `id` (required) - The ID or NAME of a project
miks's avatar
miks committed
462 463
+ `hook_id` (required) - The ID of hook to delete

464 465
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.
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481


## Branches

### List branches

Lists all branches of a project.

```
GET /projects/:id/repository/branches
```

Parameters:

+ `id` (required) - The ID of the project

Marin Jankovski's avatar
Marin Jankovski committed
482 483 484 485 486 487 488 489 490 491
```json
[
  {
    "name":"async",
    "commit": {
      "id":"a2b702edecdf41f07b42653eb1abe30ce98b9fca",
      "parents": [{
        "id":"3f94fc7c85061973edc9906ae170cc269b07ca55"
      }],
      "tree": "c68537c6534a02cc2b176ca1549f4ffa190b58ee",
492
      "message":"give caolan credit where it's due (up top)",
Marin Jankovski's avatar
Marin Jankovski committed
493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530
      "author": {
        "name":"Jeremy Ashkenas",
        "email":"jashkenas@example.com"
      },
      "committer": {
        "name":"Jeremy Ashkenas",
        "email":"jashkenas@example.com"
      },
      "authored_date":"2010-12-08T21:28:50+00:00",
      "committed_date":"2010-12-08T21:28:50+00:00"
    },
    "protected":false
  },
  {
    "name": "gh-pages",
    "commit": {
      "id": "101c10a60019fe870d21868835f65c25d64968fc",
      "parents": [{
        "id": "9c15d2e26945a665131af5d7b6d30a06ba338aaa"
      }],
      "tree": "fb5cc9d45da3014b17a876ad539976a0fb9b352a",
      "message": "Underscore.js 1.5.2",
      "author": {
        "name": "Jeremy Ashkenas",
        "email": "jashkenas@example.com"
      },
      "committer": {
        "name": "Jeremy Ashkenas",
        "email": "jashkenas@example.com"
      },
      "authored_date": "2013-09-07T12: 58: 21+00: 00",
      "committed_date": "2013-09-07T12: 58: 21+00: 00"
    },
    "protected": false
  }
]

```
531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572

### List single branch

Lists a specific branch of a project.

```
GET /projects/:id/repository/branches/:branch
```

Parameters:

+ `id` (required) - The ID of the project.
+ `branch` (required) - The name of the branch.


### Protect single branch

Protects a single branch of a project.

```
PUT /projects/:id/repository/branches/:branch/protect
```

Parameters:

+ `id` (required) - The ID of the project.
+ `branch` (required) - The name of the branch.


### Unprotect single branch

Unprotects a single branch of a project.

```
PUT /projects/:id/repository/branches/:branch/unprotect
```

Parameters:

+ `id` (required) - The ID of the project.
+ `branch` (required) - The name of the branch.

573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596

## Admin fork relation

Allows modification of the forked relationship between existing projects. . Available only for admins.

### Create a forked from/to relation between existing projects.

```
POST /projects/:id/fork/:forked_from_id
```

Parameters:

+ `id` (required) - The ID of the project
+ `forked_from_id:` (required) - The ID of the project that was forked from

### Delete an existing forked from relationship

```
DELETE /projects/:id/fork
```

Parameter:

597
+ `id` (required) - The ID of the project
598 599 600 601 602 603 604 605 606 607 608 609 610


## Search for projects by name

Search for projects by name which are public or the calling user has access to

```
GET /projects/search/:query
```

Parameters:

+   query (required) - A string contained in the project name
611 612
+   per_page (optional) - number of projects to return per page
+   page (optional) - the page to retrieve