BigW Consortium Gitlab

projects.md 14.5 KB
Newer Older
1
# Projects
2

3
## List projects
4

5
Get a list of projects accessible by the authenticated user.
6 7 8 9 10

```
GET /projects
```

11 12
Parameters:

13
- `archived` (optional) - if passed, limit by archived status
14

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

90
### List owned projects
91

92
Get a list of projects which are owned by the authenticated user.
93 94 95 96 97

```
GET /projects/owned
```

98
### List ALL projects
99 100 101 102 103 104 105

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

```
GET /projects/all
```

106
### Get single project
107

108
Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME, which is owned by the authenticated user.
Marin Jankovski committed
109
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`).
110 111 112 113 114 115 116

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

Parameters:

117
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
118

119 120
```json
{
121
  "id": 3,
122
  "description": null,
123 124
  "default_branch": "master",
  "public": false,
125
  "visibility_level": 0,
126 127 128
  "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",
129
  "owner": {
130 131 132
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13: 46: 02Z"
133
  },
134 135 136 137
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
138 139 140
  "issues_enabled": true,
  "merge_requests_enabled": true,
  "wiki_enabled": true,
141 142 143 144 145 146 147 148 149 150 151
  "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"
152
  },
Dmitriy Zaporozhets committed
153 154 155 156 157 158 159 160 161
  "permissions": {
    "project_access": {
      "access_level": 10,
      "notification_level": 3
    },
    "group_access": {
      "access_level": 50,
      "notification_level": 3
    }
162 163
  },
  "archived": false
164 165 166
}
```

167 168
### Get project events

169
Get the events for the specified project.
170 171 172 173 174 175 176 177
Sorted from newest to latest

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

Parameters:

178
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
179 180

```json
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 222 223
[
  {
    "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
224
    },
225
    "target_title": null
226
  },
227 228 229 230 231 232 233 234 235 236 237
  {
    "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"
  }
]
238 239
```

240
### Create project
241

242
Creates a new project owned by the authenticated user.
243 244 245 246 247 248 249

```
POST /projects
```

Parameters:

250
- `name` (required) - new project name
251
- `path` (optional) - custom repository name for new project. By default generated based on name
252 253 254 255 256 257 258 259 260
- `namespace_id` (optional) - namespace for the new project (defaults to user)
- `description` (optional) - short project description
- `issues_enabled` (optional)
- `merge_requests_enabled` (optional)
- `wiki_enabled` (optional)
- `snippets_enabled` (optional)
- `public` (optional) - if `true` same as setting visibility_level = 20
- `visibility_level` (optional)
- `import_url` (optional)
261

262 263
### Create project for user

264
Creates a new project owned by the specified user. Available only for admins.
265 266 267 268 269 270 271

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

Parameters:

272 273 274 275 276 277 278 279 280 281 282
- `user_id` (required) - user_id of owner
- `name` (required) - new project name
- `description` (optional) - short project description
- `default_branch` (optional) - 'master' by default
- `issues_enabled` (optional)
- `merge_requests_enabled` (optional)
- `wiki_enabled` (optional)
- `snippets_enabled` (optional)
- `public` (optional) - if `true` same as setting visibility_level = 20
- `visibility_level` (optional)
- `import_url` (optional)
283

284 285 286 287 288 289 290 291 292 293 294 295
### Fork project

Forks a project into the user namespace of the authenticated user.

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

Parameters:

- `id` (required) - The ID of the project to be forked

296
### Remove project
297

298
Removes a project including all associated resources (issues, merge requests etc.)
299 300 301 302 303 304 305

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

Parameters:

306
- `id` (required) - The ID of a project
307 308 309 310

## Team members

### List project team members
311

312
Get a list of a project's team members.
313 314

```
315
GET /projects/:id/members
316 317 318 319
```

Parameters:

320 321
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `query` (optional) - Query string to search for members
322 323

### Get project team member
324

325
Gets a project team member.
326

327 328 329 330 331
```
GET /projects/:id/members/:user_id
```

Parameters:
332

333 334
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a user
335 336 337 338

```json
{
  "id": 1,
339
  "username": "john_smith",
340 341
  "email": "john@example.com",
  "name": "John Smith",
342
  "state": "active",
343 344 345
  "created_at": "2012-05-23T08:00:58Z",
  "access_level": 40
}
346
```
347

348
### Add project team member
349

350 351
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
352
affect the existing membership.
353 354 355

```
POST /projects/:id/members
356 357 358 359
```

Parameters:

360 361 362
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a user to add
- `access_level` (required) - Project access level
363 364

### Edit project team member
365

366
Updates a project team member to a specified access level.
367 368

```
369
PUT /projects/:id/members/:user_id
370 371 372 373
```

Parameters:

374 375 376
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a team member
- `access_level` (required) - Project access level
377 378

### Remove project team member
379

380
Removes a user from a project team.
381 382

```
383
DELETE /projects/:id/members/:user_id
384 385 386 387
```

Parameters:

388 389
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `user_id` (required) - The ID of a team member
390

391 392 393
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
394
rely on the returned JSON structure.
395

396 397 398 399
## Hooks

### List project hooks

400
Get a list of project hooks.
miks committed
401 402 403 404 405 406 407

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

Parameters:

408
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
miks committed
409

410
### Get project hook
411

412
Get a specific hook for a project.
413 414 415 416 417

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

418
Parameters:
419

420 421
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `hook_id` (required) - The ID of a project hook
422

423 424 425 426
```json
{
  "id": 1,
  "url": "http://example.com/hook",
427 428 429 430
  "project_id": 3,
  "push_events": "true",
  "issues_events": "true",
  "merge_requests_events": "true",
431 432 433 434 435 436
  "created_at": "2012-10-12T17:04:47Z"
}
```

### Add project hook

437
Adds a hook to a specified project.
miks committed
438 439 440 441 442 443 444

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

Parameters:

445 446 447 448 449
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `url` (required) - The hook URL
- `push_events` - Trigger hook on push events
- `issues_events` - Trigger hook on issues events
- `merge_requests_events` - Trigger hook on merge_requests events
450
- `tag_push_events` - Trigger hook on push_tag events
451

452 453
### Edit project hook

454
Edits a hook for a specified project.
455 456 457 458 459 460 461

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

Parameters:

462 463 464 465 466 467
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `hook_id` (required) - The ID of a project hook
- `url` (required) - The hook URL
- `push_events` - Trigger hook on push events
- `issues_events` - Trigger hook on issues events
- `merge_requests_events` - Trigger hook on merge_requests events
468
- `tag_push_events` - Trigger hook on push_tag events
469

470
### Delete project hook
miks committed
471

472
Removes a hook from a project. This is an idempotent method and can be called multiple times.
473
Either the hook is available or not.
miks committed
474 475

```
476
DELETE /projects/:id/hooks/:hook_id
miks committed
477 478 479 480
```

Parameters:

481 482
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `hook_id` (required) - The ID of hook to delete
miks committed
483

484 485
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.
486 487 488 489 490 491 492 493 494 495 496 497 498

## Branches

### List branches

Lists all branches of a project.

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

Parameters:

499
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
500

501 502 503
```json
[
  {
504
    "name": "async",
505
    "commit": {
506 507 508 509 510 511
      "id": "a2b702edecdf41f07b42653eb1abe30ce98b9fca",
      "parents": [
        {
          "id": "3f94fc7c85061973edc9906ae170cc269b07ca55"
        }
      ],
512
      "tree": "c68537c6534a02cc2b176ca1549f4ffa190b58ee",
513
      "message": "give caolan credit where it's due (up top)",
514
      "author": {
515 516
        "name": "Jeremy Ashkenas",
        "email": "jashkenas@example.com"
517 518
      },
      "committer": {
519 520
        "name": "Jeremy Ashkenas",
        "email": "jashkenas@example.com"
521
      },
522 523
      "authored_date": "2010-12-08T21:28:50+00:00",
      "committed_date": "2010-12-08T21:28:50+00:00"
524
    },
525
    "protected": false
526 527 528 529 530
  },
  {
    "name": "gh-pages",
    "commit": {
      "id": "101c10a60019fe870d21868835f65c25d64968fc",
531 532 533 534 535
      "parents": [
        {
          "id": "9c15d2e26945a665131af5d7b6d30a06ba338aaa"
        }
      ],
536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552
      "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
  }
]
```
553 554 555 556 557 558 559 560 561 562 563

### List single branch

Lists a specific branch of a project.

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

Parameters:

564 565
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `branch` (required) - The name of the branch.
566 567 568 569 570 571 572 573 574 575 576

### Protect single branch

Protects a single branch of a project.

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

Parameters:

577 578
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `branch` (required) - The name of the branch.
579 580 581 582 583 584 585 586 587 588 589

### Unprotect single branch

Unprotects a single branch of a project.

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

Parameters:

590 591
- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
- `branch` (required) - The name of the branch.
592 593 594

## Admin fork relation

595
Allows modification of the forked relationship between existing projects. Available only for admins.
596 597 598 599 600 601 602 603 604

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

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

Parameters:

605 606
- `id` (required) - The ID of the project
- `forked_from_id:` (required) - The ID of the project that was forked from
607 608 609 610 611 612 613 614 615

### Delete an existing forked from relationship

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

Parameter:

616
- `id` (required) - The ID of the project
617 618 619

## Search for projects by name

620
Search for projects by name which are accessible to the authenticated user.
621 622 623 624 625 626 627

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

Parameters:

628 629 630
-   query (required) - A string contained in the project name
-   per_page (optional) - number of projects to return per page
-   page (optional) - the page to retrieve