projects.md 13.7 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

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
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,
Nihad Abbasov's avatar
Nihad Abbasov committed
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",
Nihad Abbasov's avatar
Nihad Abbasov committed
126
  "owner": {
Marin Jankovski's avatar
Marin Jankovski committed
127
128
129
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13: 46: 02Z"
Nihad Abbasov's avatar
Nihad Abbasov committed
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",
Nihad Abbasov's avatar
Nihad Abbasov committed
135
136
  "issues_enabled": true,
  "merge_requests_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
137
  "wall_enabled": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
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"
  }
Nihad Abbasov's avatar
Nihad Abbasov committed
151
152
153
}
```

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
154
155
156
157
158
159
160
161
162
163
164
### Get project events

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

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

Parameters:

165
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
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

```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
224
225
### Create project

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

```
POST /projects
```

Parameters:

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

245

246
247
248
### Create project for user

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

```
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
260
261
262
263
264
+ `issues_enabled` (optional)
+ `wall_enabled` (optional)
+ `merge_requests_enabled` (optional)
+ `wiki_enabled` (optional) 
+ `snippets_enabled` (optional)
265
266
+ `public` (optional) - if `true` same as setting visibility_level = 20
+ `visibility_level` (optional)
267

268

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

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

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

Parameters:

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

281

282
283
284
## Team members

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

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

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

Parameters:

294
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
295
+ `query` (optional) - Query string to search for members
miks's avatar
miks committed
296
297


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

300
Gets a project team member.
301
302

```
303
304
305
306
307
GET /projects/:id/members/:user_id
```

Parameters:

308
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
309
310
311
312
313
+ `user_id` (required) - The ID of a user

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


324
### Add project team member
325

326
327
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
328
affect the existing membership.
329
330
331

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

Parameters:

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

miks's avatar
miks committed
340

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

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

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

Parameters:

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


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

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

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

Parameters:

366
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
367
+ `user_id` (required) - The ID of a team member
miks's avatar
miks committed
368

369
370
371
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
372
rely on the returned JSON structure.
373
374


375
## Hooks
miks's avatar
miks committed
376

377
378
379
### List project hooks

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

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

Parameters:

387
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
miks's avatar
miks committed
388
389


390
### Get project hook
391

392
Get a specific hook for project.
393
394
395
396
397
398
399

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

Parameters:

400
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
401
402
+ `hook_id` (required) - The ID of a project hook

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

miks's avatar
miks committed
415

416
417
418
### Add project hook

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

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

Parameters:

426
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
miks's avatar
miks committed
427
+ `url` (required) - The hook URL
428
429
430
+ `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
431
432


433
### Edit project hook
434

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

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

Parameters:

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


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

453
454
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
455
456

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

Parameters:

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

465
466
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.
467
468


469
## Branches
miks's avatar
miks committed
470

471
472
473
### List branches

Lists all branches of a project.
miks's avatar
miks committed
474
475

```
476
477
478
479
480
GET /projects/:id/repository/branches
```

Parameters:

481
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
482

Marin Jankovski's avatar
Marin Jankovski committed
483
484
485
486
487
488
489
490
491
492
```json
[
  {
    "name":"async",
    "commit": {
      "id":"a2b702edecdf41f07b42653eb1abe30ce98b9fca",
      "parents": [{
        "id":"3f94fc7c85061973edc9906ae170cc269b07ca55"
      }],
      "tree": "c68537c6534a02cc2b176ca1549f4ffa190b58ee",
493
      "message":"give caolan credit where it's due (up top)",
Marin Jankovski's avatar
Marin Jankovski committed
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
531
      "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
  }
]

```
532
533
534
535
536
537
538

### List single branch

Lists a specific branch of a project.

```
GET /projects/:id/repository/branches/:branch
miks's avatar
miks committed
539
540
541
542
```

Parameters:

543
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
544
545
546
547
548
549
550
551
552
553
554
555
+ `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:
miks's avatar
miks committed
556

557
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
558
559
560
561
562
563
564
565
566
567
568
569
570
+ `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:

571
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
572
+ `branch` (required) - The name of the branch.
Matt Humphrey's avatar
Matt Humphrey committed
573

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

## 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:

598
+ `id` (required) - The ID of the project
Izaak Alpert's avatar
Izaak Alpert committed
599
600
601
602
603
604
605
606
607
608
609
610
611


## 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
612
613
+   per_page (optional) - number of projects to return per page
+   page (optional) - the page to retrieve