services.md 38.4 KB
Newer Older
1
# Services API
Kevin Houdebert's avatar
Kevin Houdebert committed
2

Mark Chao's avatar
Mark Chao committed
3
>**Note:** This API requires an access token with Maintainer or Owner permissions
4

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
5
6
7
8
9
10
11
12
## Asana

Asana - Teamwork without email

### Create/Edit Asana service

Set Asana service for a project.

13
> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found will get the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your API Keys here: <https://asana.com/developers/documentation/getting-started/auth#api-key>.
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
14
15
16
17
18
19
20

```
PUT /projects/:id/services/asana
```

Parameters:

21
22
23
24
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `api_key` | string | true | User API token. User must have access to task, all comments will be attributed to this user. |
| `restrict_to_branch` | string | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. |
25
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
26
27
28
29
30
31
32
33
34

### Delete Asana service

Delete Asana service for a project.

```
DELETE /projects/:id/services/asana
```

35
36
37
38
39
40
41
42
### Get Asana service settings

Get Asana service settings for a project.

```
GET /projects/:id/services/asana
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
## Assembla

Project Management Software (Source Commits Endpoint)

### Create/Edit Assembla service

Set Assembla service for a project.

```
PUT /projects/:id/services/assembla
```

Parameters:

57
58
59
60
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | The authentication token
| `subdomain` | string | false | The subdomain setting |
61
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
62
63
64
65
66
67
68
69
70

### Delete Assembla service

Delete Assembla service for a project.

```
DELETE /projects/:id/services/assembla
```

71
72
73
74
75
76
77
78
### Get Assembla service settings

Get Assembla service settings for a project.

```
GET /projects/:id/services/assembla
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
79
80
## Atlassian Bamboo CI

81
A continuous integration and build server
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
82
83
84
85
86
87
88
89
90
91
92
93
94

### Create/Edit Atlassian Bamboo CI service

Set Atlassian Bamboo CI service for a project.

> You must set up automatic revision labeling and a repository trigger in Bamboo.

```
PUT /projects/:id/services/bamboo
```

Parameters:

95
96
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
97
| `bamboo_url` | string | true | Bamboo root URL. For example, `https://bamboo.example.com`. |
98
99
100
| `build_key` | string | true | Bamboo build plan key like KEY |
| `username` | string | true | A user with API access, if applicable |
| `password` | string | true | Password of the user |
101
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
102
103
104
105
106
107
108
109
110

### Delete Atlassian Bamboo CI service

Delete Atlassian Bamboo CI service for a project.

```
DELETE /projects/:id/services/bamboo
```

111
112
113
114
115
116
117
118
### Get Atlassian Bamboo CI service settings

Get Atlassian Bamboo CI service settings for a project.

```
GET /projects/:id/services/bamboo
```

Mark Fletcher's avatar
Mark Fletcher committed
119
120
121
122
## Bugzilla

Bugzilla Issue Tracker

Evan Read's avatar
Evan Read committed
123
### Create/Edit Bugzilla service
Mark Fletcher's avatar
Mark Fletcher committed
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

Set Bugzilla service for a project.

```
PUT /projects/:id/services/bugzilla
```

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `new_issue_url` | string | true |  New Issue url |
| `issues_url` | string | true | Issue url |
| `project_url` | string | true | Project url |
| `description` | string | false | Description |
| `title` | string | false | Title |
140
| `push_events` | boolean | false | Enable notifications for push events |
Mark Fletcher's avatar
Mark Fletcher committed
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

### Delete Bugzilla Service

Delete Bugzilla service for a project.

```
DELETE /projects/:id/services/bugzilla
```

### Get Bugzilla Service Settings

Get Bugzilla service settings for a project.

```
GET /projects/:id/services/bugzilla
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
158
159
160
161
162
163
164
165
166
## Buildkite

Continuous integration and deployments

### Create/Edit Buildkite service

Set Buildkite service for a project.

```
167
PUT /projects/:id/services/buildkite
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
168
169
170
171
```

Parameters:

172
173
174
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Buildkite project GitLab token |
Evan Read's avatar
Evan Read committed
175
| `project_url` | string | true | `https://buildkite.com/example/project` |
176
| `enable_ssl_verification` | boolean | false | Enable SSL verification |
177
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
178
179
180
181
182
183

### Delete Buildkite service

Delete Buildkite service for a project.

```
184
DELETE /projects/:id/services/buildkite
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
185
186
```

187
188
189
190
191
### Get Buildkite service settings

Get Buildkite service settings for a project.

```
192
GET /projects/:id/services/buildkite
193
194
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
195
196
197
198
199
200
201
202
203
204
205
206
207
208
## Campfire

Simple web-based real-time group chat

### Create/Edit Campfire service

Set Campfire service for a project.

```
PUT /projects/:id/services/campfire
```

Parameters:

209
210
211
212
213
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Campfire token |
| `subdomain` | string | false | Campfire subdomain |
| `room`  | string | false | Campfire room |
214
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
215
216
217
218
219
220
221
222
223

### Delete Campfire service

Delete Campfire service for a project.

```
DELETE /projects/:id/services/campfire
```

224
225
226
227
228
229
230
231
### Get Campfire service settings

Get Campfire service settings for a project.

```
GET /projects/:id/services/campfire
```

232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
## Unify Circuit

Unify Circuit RTC and collaboration tool.

### Create/Edit Unify Circuit service

Set Unify Circuit service for a project.

```
PUT /projects/:id/services/unify-circuit
```

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `webhook` | string | true | The Unify Circuit webhook. For example, `https://circuit.com/rest/v2/webhooks/incoming/...`. |
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" |
| `push_events` | boolean | false | Enable notifications for push events |
| `issues_events` | boolean | false | Enable notifications for issue events |
| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
| `note_events` | boolean | false | Enable notifications for note events |
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |

### Delete Unify Circuit service

Delete Unify Circuit service for a project.

```
DELETE /projects/:id/services/unify-circuit
```

### Get Unify Circuit service settings

Get Unify Circuit service settings for a project.

```
GET /projects/:id/services/unify-circuit
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
277
278
279
280
281
282
283
284
285
286
287
288
289
290
## Custom Issue Tracker

Custom issue tracker

### Create/Edit Custom Issue Tracker service

Set Custom Issue Tracker service for a project.

```
PUT /projects/:id/services/custom-issue-tracker
```

Parameters:

291
292
293
294
295
296
297
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `new_issue_url` | string | true |  New Issue url
| `issues_url` | string | true | Issue url
| `project_url` | string | true | Project url
| `description` | string | false | Description
| `title` | string | false | Title
298
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
299
300
301
302
303
304
305
306
307

### Delete Custom Issue Tracker service

Delete Custom Issue Tracker service for a project.

```
DELETE /projects/:id/services/custom-issue-tracker
```

308
309
310
311
312
313
314
315
### Get Custom Issue Tracker service settings

Get Custom Issue Tracker service settings for a project.

```
GET /projects/:id/services/custom-issue-tracker
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
316
317
318
319
320
321
322
323
324
325
326
327
328
329
## Drone CI

Drone is a Continuous Integration platform built on Docker, written in Go

### Create/Edit Drone CI service

Set Drone CI service for a project.

```
PUT /projects/:id/services/drone-ci
```

Parameters:

330
331
332
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Drone CI project specific token |
Evan Read's avatar
Evan Read committed
333
| `drone_url` | string | true | `http://drone.example.com` |
334
| `enable_ssl_verification` | boolean | false | Enable SSL verification |
335
336
337
338
| `push_events` | boolean | false | Enable notifications for push events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
339
340
341
342
343
344
345
346
### Delete Drone CI service

Delete Drone CI service for a project.

```
DELETE /projects/:id/services/drone-ci
```

347
348
349
350
351
352
353
354
### Get Drone CI service settings

Get Drone CI service settings for a project.

```
GET /projects/:id/services/drone-ci
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
355
356
357
358
359
360
361
362
363
364
365
366
367
368
## Emails on push

Email the commits and diff of each push to a list of recipients.

### Create/Edit Emails on push service

Set Emails on push service for a project.

```
PUT /projects/:id/services/emails-on-push
```

Parameters:

369
370
371
372
373
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `recipients` | string | true | Emails separated by whitespace |
| `disable_diffs` | boolean | false | Disable code diffs |
| `send_from_committer_email` | boolean | false | Send from committer |
374
375
| `push_events` | boolean | false | Enable notifications for push events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
376
377
378
379
380
381
382
383
384

### Delete Emails on push service

Delete Emails on push service for a project.

```
DELETE /projects/:id/services/emails-on-push
```

385
386
387
388
389
390
391
392
### Get Emails on push service settings

Get Emails on push service settings for a project.

```
GET /projects/:id/services/emails-on-push
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
393
394
395
396
397
398
399
400
401
402
403
404
405
406
## External Wiki

Replaces the link to the internal wiki with a link to an external wiki.

### Create/Edit External Wiki service

Set External Wiki service for a project.

```
PUT /projects/:id/services/external-wiki
```

Parameters:

407
408
409
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `external_wiki_url` | string | true | The URL of the external Wiki |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
410
411
412
413
414
415
416
417
418

### Delete External Wiki service

Delete External Wiki service for a project.

```
DELETE /projects/:id/services/external-wiki
```

419
420
421
422
423
424
425
426
### Get External Wiki service settings

Get External Wiki service settings for a project.

```
GET /projects/:id/services/external-wiki
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
427
428
429
430
431
432
433
434
435
436
437
438
439
440
## Flowdock

Flowdock is a collaboration web app for technical teams.

### Create/Edit Flowdock service

Set Flowdock service for a project.

```
PUT /projects/:id/services/flowdock
```

Parameters:

441
442
443
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Flowdock Git source token |
444
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
445
446
447
448
449
450
451
452
453

### Delete Flowdock service

Delete Flowdock service for a project.

```
DELETE /projects/:id/services/flowdock
```

454
455
456
457
458
459
460
461
### Get Flowdock service settings

Get Flowdock service settings for a project.

```
GET /projects/:id/services/flowdock
```

462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
## GitHub **(PREMIUM)**

Code collaboration software.

### Create/Edit GitHub service

Set GitHub service for a project.

```
PUT /projects/:id/services/github
```

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | GitHub API token with `repo:status` OAuth scope |
| `repository_url` | string | true | GitHub repository URL |
| `static_context` | boolean | false | Append instance name instead of branch to [status check name](../user/project/integrations/github.md#static--dynamic-status-check-names) |

### Delete GitHub service

Delete GitHub service for a project.

```
DELETE /projects/:id/services/github
```

### Get GitHub service settings

Get GitHub service settings for a project.

```
GET /projects/:id/services/github
```

498
499
500
501
## Hangouts Chat

Google GSuite team collaboration tool.

502
>**Note:** This service was [introduced in v11.2](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/20290)
503

504
505
506
507
508
### Create/Edit Hangouts Chat service

Set Hangouts Chat service for a project.

```
509
PUT /projects/:id/services/hangouts-chat
510
511
512
513
514
515
516
517
```

>**Note:** Specific event parameters (e.g. `push_events` flag) were [introduced in v10.4][11435]

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
518
| `webhook` | string | true | The Hangouts Chat webhook. For example, `https://chat.googleapis.com/v1/spaces...`. |
519
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
520
521
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" |
522
523
524
525
526
527
| `push_events` | boolean | false | Enable notifications for push events |
| `issues_events` | boolean | false | Enable notifications for issue events |
| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
| `note_events` | boolean | false | Enable notifications for note events |
528
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
529
530
531
532
533
534
535
536
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |

### Delete Hangouts Chat service

Delete Hangouts Chat service for a project.

```
537
DELETE /projects/:id/services/hangouts-chat
538
539
540
541
542
543
544
```

### Get Hangouts Chat service settings

Get Hangouts Chat service settings for a project.

```
545
GET /projects/:id/services/hangouts-chat
546
547
```

548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
## HipChat

Private group chat and IM

### Create/Edit HipChat service

Set HipChat service for a project.

```
PUT /projects/:id/services/hipchat
```

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Room token |
| `color` | string | false | The room color |
| `notify` | boolean | false | Enable notifications |
| `room` | string | false |Room name or ID |
| `api_version` | string | false | Leave blank for default (v2) |
| `server` | string | false | Leave blank for default. For example, `https://hipchat.example.com`. |
570
571
572
573
574
575
576
577
| `push_events` | boolean | false | Enable notifications for push events |
| `issues_events` | boolean | false | Enable notifications for issue events |
| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
| `note_events` | boolean | false | Enable notifications for note events |
| `confidental_note_events` | boolean | false | Enable notifications for confidential note events |
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594

### Delete HipChat service

Delete HipChat service for a project.

```
DELETE /projects/:id/services/hipchat
```

### Get HipChat service settings

Get HipChat service settings for a project.

```
GET /projects/:id/services/hipchat
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
595
596
597
598
599
600
601
602
## Irker (IRC gateway)

Send IRC messages, on update, to a list of recipients through an Irker gateway.

### Create/Edit Irker (IRC gateway) service

Set Irker (IRC gateway) service for a project.

Evan Read's avatar
Evan Read committed
603
> NOTE: Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a  firewall. Please make sure you run the daemon within a secured network  to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>.
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
604
605
606
607
608
609
610

```
PUT /projects/:id/services/irker
```

Parameters:

611
612
613
614
615
616
617
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `recipients` | string | true | Recipients/channels separated by whitespaces |
| `default_irc_uri` | string | false | irc://irc.network.net:6697/ |
| `server_host` | string | false | localhost |
| `server_port` | integer | false | 6659 |
| `colorize_messages` | boolean | false | Colorize messages |
618
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
619
620
621
622
623
624
625
626
627

### Delete Irker (IRC gateway) service

Delete Irker (IRC gateway) service for a project.

```
DELETE /projects/:id/services/irker
```

628
629
630
631
632
633
634
635
### Get Irker (IRC gateway) service settings

Get Irker (IRC gateway) service settings for a project.

```
GET /projects/:id/services/irker
```

Takuya Noguchi's avatar
Takuya Noguchi committed
636
## Jira
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
637

Takuya Noguchi's avatar
Takuya Noguchi committed
638
Jira issue tracker.
639

Takuya Noguchi's avatar
Takuya Noguchi committed
640
### Get Jira service settings
641

Takuya Noguchi's avatar
Takuya Noguchi committed
642
Get Jira service settings for a project.
643
644
645
646

```
GET /projects/:id/services/jira
```
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
647

Takuya Noguchi's avatar
Takuya Noguchi committed
648
### Create/Edit Jira service
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
649

Takuya Noguchi's avatar
Takuya Noguchi committed
650
Set Jira service for a project.
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
651

Evan Read's avatar
Evan Read committed
652
> Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and
Blair Lunceford's avatar
Blair Lunceford committed
653
> `project_url` are replaced by `url`. If you are using an
654
> older version, [follow this documentation](https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable-ee/doc/api/services.md#jira).
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
655
656
657
658
659

```
PUT /projects/:id/services/jira
```

660
661
662
Parameters:

| Parameter | Type | Required | Description |
663
| --------- | ---- | -------- | ----------- |
Takuya Noguchi's avatar
Takuya Noguchi committed
664
665
666
667
| `url`           | string | yes | The URL to the Jira project which is being linked to this GitLab project. For example, `https://jira.example.com`. |
| `api_url`   | string | no | The base URL to the Jira instance API. Web URL value will be used if not set. For example, `https://jira-api.example.com`. |
| `username`      | string | yes  | The username of the user created to be used with GitLab/Jira. |
| `password`      | string | yes  | The password of the user created to be used with GitLab/Jira. |
668
| `active`        | boolean | no  | Activates or deactivates the service. Defaults to false (deactivated). |
669
| `jira_issue_transition_id` | string | no | The ID of a transition that moves issues to a closed state. You can find this number under the Jira workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column. By default, this ID is set to `2`. |
670
671
| `commit_events` | boolean | false | Enable notifications for commit events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
672

Takuya Noguchi's avatar
Takuya Noguchi committed
673
### Delete Jira service
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
674

Takuya Noguchi's avatar
Takuya Noguchi committed
675
Remove all previously Jira settings from a project.
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
676
677
678
679
680

```
DELETE /projects/:id/services/jira
```

681
## Slack slash commands
Robert Schilling's avatar
Robert Schilling committed
682

683
Ability to receive slash commands from a Slack chat instance.
Robert Schilling's avatar
Robert Schilling committed
684

685
### Get Slack slash command service settings
Robert Schilling's avatar
Robert Schilling committed
686

687
Get Slack slash command service settings for a project.
Robert Schilling's avatar
Robert Schilling committed
688
689

```
690
691
692
693
694
695
696
697
698
699
700
701
702
703
GET /projects/:id/services/slack-slash-commands
```

Example response:

```json
{
  "id": 4,
  "title": "Slack slash commands",
  "created_at": "2017-06-27T05:51:39-07:00",
  "updated_at": "2017-06-27T05:51:39-07:00",
  "active": true,
  "push_events": true,
  "issues_events": true,
704
  "confidential_issues_events": true,
705
706
707
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
708
  "job_events": true,
709
710
  "pipeline_events": true,
  "properties": {
711
    "token": "<your_access_token>"
712
713
714
715
716
717
718
719
720
721
  }
}
```

### Create/Edit Slack slash command service

Set Slack slash command for a project.

```
PUT /projects/:id/services/slack-slash-commands
Robert Schilling's avatar
Robert Schilling committed
722
723
724
725
```

Parameters:

726
| Parameter | Type | Required | Description |
Robert Schilling's avatar
Robert Schilling committed
727
| --------- | ---- | -------- | ----------- |
728
| `token` | string | yes | The Slack token |
Robert Schilling's avatar
Robert Schilling committed
729

730
### Delete Slack slash command service
Robert Schilling's avatar
Robert Schilling committed
731

732
Delete Slack slash command service for a project.
Robert Schilling's avatar
Robert Schilling committed
733
734

```
735
DELETE /projects/:id/services/slack-slash-commands
Robert Schilling's avatar
Robert Schilling committed
736
737
```

738
739
740
741
742
## Mattermost slash commands

Ability to receive slash commands from a Mattermost chat instance.

### Get Mattermost slash command service settings
Robert Schilling's avatar
Robert Schilling committed
743

744
Get Mattermost slash command service settings for a project.
Robert Schilling's avatar
Robert Schilling committed
745
746
747
748
749

```
GET /projects/:id/services/mattermost-slash-commands
```

750
751
752
753
754
755
756
757
758
759
### Create/Edit Mattermost slash command service

Set Mattermost slash command for a project.

```
PUT /projects/:id/services/mattermost-slash-commands
```

Parameters:

760
| Parameter | Type | Required | Description |
761
762
| --------- | ---- | -------- | ----------- |
| `token` | string | yes | The Mattermost token |
763
| `username` | string | no | The username to use to post the message |
764
765
766
767
768
769
770
771
772

### Delete Mattermost slash command service

Delete Mattermost slash command service for a project.

```
DELETE /projects/:id/services/mattermost-slash-commands
```

Matt Coleman's avatar
Matt Coleman committed
773
774
775
776
777
778
779
780
781
782
783
784
785
786
## Packagist

Update your project on Packagist, the main Composer repository, when commits or tags are pushed to GitLab.

### Create/Edit Packagist service

Set Packagist service for a project.

```
PUT /projects/:id/services/packagist
```

Parameters:

787
788
789
790
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `username` | string | yes | The username of a Packagist account |
| `token` | string | yes | API token to the Packagist server |
Evan Read's avatar
Evan Read committed
791
| `server` | boolean | no | URL of the Packagist server. Leave blank for default: <https://packagist.org> |
792
793
794
| `push_events` | boolean | false | Enable notifications for push events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
Matt Coleman's avatar
Matt Coleman committed
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811

### Delete Packagist service

Delete Packagist service for a project.

```
DELETE /projects/:id/services/packagist
```

### Get Packagist service settings

Get Packagist service settings for a project.

```
GET /projects/:id/services/packagist
```

Robert Schilling's avatar
Robert Schilling committed
812
813
814
815
816
817
818
819
820
821
822
823
824
825
## Pipeline-Emails

Get emails for GitLab CI pipelines.

### Create/Edit Pipeline-Emails service

Set Pipeline-Emails service for a project.

```
PUT /projects/:id/services/pipelines-email
```

Parameters:

826
| Parameter | Type | Required | Description |
Robert Schilling's avatar
Robert Schilling committed
827
828
829
| --------- | ---- | -------- | ----------- |
| `recipients` | string | yes | Comma-separated list of recipient email addresses |
| `add_pusher` | boolean | no | Add pusher to recipients list |
Kamil Trzciński's avatar
Kamil Trzciński committed
830
| `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines |
831
| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" |
832
| `notify_only_default_branch` | boolean | no | Send notifications only for the default branch ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/28271)) |
833
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
Robert Schilling's avatar
Robert Schilling committed
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850

### Delete Pipeline-Emails service

Delete Pipeline-Emails service for a project.

```
DELETE /projects/:id/services/pipelines-email
```

### Get Pipeline-Emails service settings

Get Pipeline-Emails service settings for a project.

```
GET /projects/:id/services/pipelines-email
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
851
852
853
854
855
856
857
858
859
860
861
862
863
864
## PivotalTracker

Project Management Software (Source Commits Endpoint)

### Create/Edit PivotalTracker service

Set PivotalTracker service for a project.

```
PUT /projects/:id/services/pivotaltracker
```

Parameters:

865
866
867
868
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | The PivotalTracker token |
| `restrict_to_branch` | boolean | false | Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches. |
869
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
870
871
872
873
874
875
876
877
878

### Delete PivotalTracker service

Delete PivotalTracker service for a project.

```
DELETE /projects/:id/services/pivotaltracker
```

879
880
881
882
883
884
885
886
### Get PivotalTracker service settings

Get PivotalTracker service settings for a project.

```
GET /projects/:id/services/pivotaltracker
```

887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
## Prometheus

Prometheus is a powerful time-series monitoring service.

### Create/Edit Prometheus service

Set Prometheus service for a project.

```
PUT /projects/:id/services/prometheus
```

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
903
| `api_url` | string | true | Prometheus API Base URL. For example, `http://prometheus.example.com/`. |
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920

### Delete Prometheus service

Delete Prometheus service for a project.

```
DELETE /projects/:id/services/prometheus
```

### Get Prometheus service settings

Get Prometheus service settings for a project.

```
GET /projects/:id/services/prometheus
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
921
922
923
924
925
926
927
928
929
930
931
932
933
934
## Pushover

Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop.

### Create/Edit Pushover service

Set Pushover service for a project.

```
PUT /projects/:id/services/pushover
```

Parameters:

935
936
937
938
939
940
941
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `api_key` | string | true | Your application key |
| `user_key` | string | true | Your user key |
| `priority` | string | true | The priority |
| `device` | string | false | Leave blank for all active devices |
| `sound` | string | false | The sound of the notification |
942
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
943
944
945
946
947
948
949
950
951

### Delete Pushover service

Delete Pushover service for a project.

```
DELETE /projects/:id/services/pushover
```

952
953
954
955
956
957
958
959
### Get Pushover service settings

Get Pushover service settings for a project.

```
GET /projects/:id/services/pushover
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
960
961
962
963
964
965
966
967
968
969
970
971
972
973
## Redmine

Redmine issue tracker

### Create/Edit Redmine service

Set Redmine service for a project.

```
PUT /projects/:id/services/redmine
```

Parameters:

974
975
976
977
978
979
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `new_issue_url` | string | true | New Issue url |
| `project_url` | string | true | Project url |
| `issues_url` | string | true | Issue url |
| `description` | string | false | Description |
980
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
981
982
983
984
985
986
987
988
989

### Delete Redmine service

Delete Redmine service for a project.

```
DELETE /projects/:id/services/redmine
```

990
991
992
993
994
995
996
997
### Get Redmine service settings

Get Redmine service settings for a project.

```
GET /projects/:id/services/redmine
```

998
## Slack notifications
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
999

1000
Receive event notifications in Slack
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
1001
1002
1003
1004
1005
1006
1007
1008
1009

### Create/Edit Slack service

Set Slack service for a project.

```
PUT /projects/:id/services/slack
```

1010
1011
>**Note:** Specific event parameters (e.g. `push_events` flag and `push_channel`) were [introduced in v10.4][11435]

1012
Parameters:
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
1013

1014
1015
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
1016
| `webhook` | string | true | `https://hooks.slack.com/services/...` |
1017
1018
1019
| `username` | string | false | username |
| `channel` | string | false | Default channel to use if others are not configured |
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
1020
1021
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" |
1022
1023
| `commit_events` | boolean | false | Enable notifications for commit events |
| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications |
1024
| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
1025
1026
1027
1028
1029
1030
1031
1032
| `confidential_note_channel` | string | false | The name of the channel to receive confidential note events notifications |
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
| `deployment_channel` | string | false | The name of the channel to receive deployment events notifications |
| `deployment_events` | boolean | false | Enable notifications for deployment events |
| `issue_channel` | string | false | The name of the channel to receive issues events notifications |
| `issues_events` | boolean | false | Enable notifications for issue events |
| `job_events` | boolean | false | Enable notifications for job events |
| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications |
1033
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
1034
| `note_channel` | string | false | The name of the channel to receive note events notifications |
1035
| `note_events` | boolean | false | Enable notifications for note events |
1036
| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications |
1037
1038
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
| `push_channel` | string | false | The name of the channel to receive push events notifications |
1039
| `push_events` | boolean | false | Enable notifications for push events |
1040
| `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications |
1041
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
1042
| `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications |
1043
| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
1044
1045
1046
1047
1048
1049
1050
1051
1052

### Delete Slack service

Delete Slack service for a project.

```
DELETE /projects/:id/services/slack
```

1053
1054
1055
1056
1057
1058
1059
1060
### Get Slack service settings

Get Slack service settings for a project.

```
GET /projects/:id/services/slack
```

1061
1062
1063
1064
1065
1066
1067
1068
1069
## Microsoft Teams

Group Chat Software

### Create/Edit Microsoft Teams service

Set Microsoft Teams service for a project.

```
1070
PUT /projects/:id/services/microsoft-teams
1071
1072
1073
1074
1075
1076
```

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
1077
| `webhook` | string | true | The Microsoft Teams webhook. For example, `https://outlook.office.com/webhook/...` |
1078
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
1079
1080
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" |
1081
1082
1083
1084
1085
1086
1087
1088
1089
| `push_events` | boolean | false | Enable notifications for push events |
| `issues_events` | boolean | false | Enable notifications for issue events |
| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
| `note_events` | boolean | false | Enable notifications for note events |
| `confidental_note_events` | boolean | false | Enable notifications for confidential note events |
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
1090
1091
1092
1093
1094
1095

### Delete Microsoft Teams service

Delete Microsoft Teams service for a project.

```
1096
DELETE /projects/:id/services/microsoft-teams
1097
1098
1099
1100
1101
1102
1103
```

### Get Microsoft Teams service settings

Get Microsoft Teams service settings for a project.

```
1104
GET /projects/:id/services/microsoft-teams
1105
1106
```

1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
## Mattermost notifications

Receive event notifications in Mattermost

### Create/Edit Mattermost notifications service

Set Mattermost service for a project.

```
PUT /projects/:id/services/mattermost
```

1119
>**Note:** Specific event parameters (e.g. `push_events` flag and `push_channel`) were [introduced in v10.4][11435]
1120

1121
Parameters:
1122
1123
1124

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
1125
| `webhook` | string | true | The Mattermost webhook. For example, `http://mattermost_host/hooks/...` |
1126
1127
1128
| `username` | string | false | username |
| `channel` | string | false | Default channel to use if others are not configured |
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
1129
1130
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" |
1131
1132
1133
1134
1135
1136
| `push_events` | boolean | false | Enable notifications for push events |
| `issues_events` | boolean | false | Enable notifications for issue events |
| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
| `note_events` | boolean | false | Enable notifications for note events |
1137
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
1138
1139
1140
1141
1142
1143
1144
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
| `push_channel` | string | false | The name of the channel to receive push events notifications |
| `issue_channel` | string | false | The name of the channel to receive issues events notifications |
| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications |
| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications |
| `note_channel` | string | false | The name of the channel to receive note events notifications |
1145
| `confidential_note_channel` | boolean | The name of the channel to receive confidential note events notifications |
1146
1147
1148
| `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications |
| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications |
| `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications |
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165

### Delete Mattermost notifications service

Delete Mattermost Notifications service for a project.

```
DELETE /projects/:id/services/mattermost
```

### Get Mattermost notifications service settings

Get Mattermost notifications service settings for a project.

```
GET /projects/:id/services/mattermost
```

Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
## JetBrains TeamCity CI

A continuous integration and build server

### Create/Edit JetBrains TeamCity CI service

Set JetBrains TeamCity CI service for a project.

> The build configuration in Teamcity must use the build format number %build.vcs.number% you will also want to configure monitoring of all branches so merge requests build, that setting is in the vsc root advanced settings.

```
PUT /projects/:id/services/teamcity
```

Parameters:

1182
1183
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
1184
| `teamcity_url` | string | true | TeamCity root URL. For example, `https://teamcity.example.com` |
1185
1186
1187
| `build_type` | string | true | Build configuration ID |
| `username` | string | true | A user with permissions to trigger a manual build |
| `password` | string | true | The password of the user |
1188
| `push_events` | boolean | false | Enable notifications for push events |
Kirilll Zaitsev's avatar
Kirilll Zaitsev committed
1189
1190
1191
1192
1193
1194
1195
1196
1197

### Delete JetBrains TeamCity CI service

Delete JetBrains TeamCity CI service for a project.

```
DELETE /projects/:id/services/teamcity
```

1198
1199
1200
1201
1202
1203
1204
### Get JetBrains TeamCity CI service settings

Get JetBrains TeamCity CI service settings for a project.

```
GET /projects/:id/services/teamcity
```
1205

1206
## Jenkins CI **(STARTER)**
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219

A continuous integration and build server

### Create/Edit Jenkins CI service

Set Jenkins CI service for a project.

```
PUT /projects/:id/services/jenkins
```

Parameters:

Evan Read's avatar
Evan Read committed
1220
- `jenkins_url` (**required**) - Jenkins URL like `http://jenkins.example.com`
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
- `project_name` (**required**) - The URL-friendly project name. Example: my_project_name
- `username` (optional) - A user with access to the Jenkins server, if applicable
- `password` (optional) - The password of the user

### Delete Jenkins CI service

Delete Jenkins CI service for a project.

```
DELETE /projects/:id/services/jenkins
```

### Get Jenkins CI service settings

Get Jenkins CI service settings for a project.

```
GET /projects/:id/services/jenkins
```

## Jenkins CI (Deprecated) Service

A continuous integration and build server

### Create/Edit Jenkins CI (Deprecated) service

Set Jenkins CI (Deprecated) service for a project.

```
PUT /projects/:id/services/jenkins-deprecated
```

Parameters:

Evan Read's avatar
Evan Read committed
1255
- `project_url` (**required**) - Jenkins project URL like `http://jenkins.example.com/job/my-project/`
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
- `multiproject_enabled` (optional) - Multi-project mode is configured in Jenkins GitLab Hook plugin
- `pass_unstable` (optional) - Unstable builds will be treated as passing

### Delete Jenkins CI (Deprecated) service

Delete Jenkins CI (Deprecated) service for a project.

```
DELETE /projects/:id/services/jenkins-deprecated
```

### Get Jenkins CI (Deprecated) service settings

Get Jenkins CI (Deprecated) service settings for a project.

```
GET /projects/:id/services/jenkins-deprecated
```

Eric Eastwood's avatar
Eric Eastwood committed
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
## MockCI

Mock an external CI. See [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service) for an example of a companion mock service.

This service is only available when your environment is set to development.

### Create/Edit MockCI service

Set MockCI service for a project.

```
PUT /projects/:id/services/mock-ci
```

Parameters:

1291
1292
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
Evan Read's avatar
Evan Read committed
1293
| `mock_service_url` | string | true | `http://localhost:4004` |
Eric Eastwood's avatar
Eric Eastwood committed
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309

### Delete MockCI service

Delete MockCI service for a project.

```
DELETE /projects/:id/services/mock-ci
```

### Get MockCI service settings

Get MockCI service settings for a project.

```
GET /projects/:id/services/mock-ci
```
1310

1311
[11435]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/11435
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331

## YouTrack

YouTrack issue tracker

### Create/Edit YouTrack service

Set YouTrack service for a project.

```
PUT /projects/:id/services/youtrack
```

Parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `issues_url` | string | true | Issue url |
| `project_url` | string | true | Project url |
| `description` | string | false | Description |
1332
| `push_events` | boolean | false | Enable notifications for push events |
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348

### Delete YouTrack Service

Delete YouTrack service for a project.

```
DELETE /projects/:id/services/youtrack
```

### Get YouTrack Service Settings

Get YouTrack service settings for a project.

```
GET /projects/:id/services/youtrack
```