debian-mirror-gitlab/doc/api/services.md

1505 lines
44 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
2021-03-08 18:12:59 +05:30
stage: Create
group: Ecosystem
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2021-04-17 20:07:23 +05:30
# Services API **(FREE)**
2015-04-26 12:48:37 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2020-10-24 23:57:45 +05:30
This API requires an access token with Maintainer or Owner permissions
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
## List all active services
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21330) in GitLab 12.7.
Get a list of all active project services.
2020-04-08 14:13:33 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
GET /projects/:id/services
```
Example response:
```json
[
{
"id": 75,
"title": "Jenkins CI",
"slug": "jenkins",
"created_at": "2019-11-20T11:20:25.297Z",
"updated_at": "2019-11-20T12:24:37.498Z",
"active": true,
"commit_events": true,
"push_events": true,
"issues_events": true,
"confidential_issues_events": true,
"merge_requests_events": true,
"tag_push_events": false,
"note_events": true,
"confidential_note_events": true,
"pipeline_events": true,
"wiki_page_events": true,
"job_events": true,
"comment_on_event_enabled": true
}
{
"id": 76,
"title": "Alerts endpoint",
"slug": "alerts",
"created_at": "2019-11-20T11:20:25.297Z",
"updated_at": "2019-11-20T12:24:37.498Z",
"active": true,
"commit_events": true,
"push_events": true,
"issues_events": true,
"confidential_issues_events": true,
"merge_requests_events": true,
"tag_push_events": true,
"note_events": true,
"confidential_note_events": true,
"pipeline_events": true,
"wiki_page_events": true,
"job_events": true,
"comment_on_event_enabled": true
}
]
```
2015-09-25 12:07:36 +05:30
## Asana
Asana - Teamwork without email
### Create/Edit Asana service
Set Asana service for a project.
2021-02-22 17:27:13 +05:30
> 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 gets 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://developers.asana.com/docs/#authentication-basics>.
2015-09-25 12:07:36 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/asana
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-02-22 17:27:13 +05:30
| `api_key` | string | true | User API token. User must have access to task, all comments are attributed to this user. |
| `restrict_to_branch` | string | false | Comma-separated list of branches which are automatically inspected. Leave blank to include all branches. |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Asana service
Delete Asana service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/asana
```
### Get Asana service settings
Get Asana service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/asana
```
## Assembla
Project Management Software (Source Commits Endpoint)
### Create/Edit Assembla service
Set Assembla service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/assembla
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | The authentication token
| `subdomain` | string | false | The subdomain setting |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Assembla service
Delete Assembla service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/assembla
```
### Get Assembla service settings
Get Assembla service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/assembla
```
## Atlassian Bamboo CI
A continuous integration and build server
### 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.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/bamboo
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `bamboo_url` | string | true | Bamboo root URL. For example, `https://bamboo.example.com`. |
2018-03-17 18:26:18 +05:30
| `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 |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Atlassian Bamboo CI service
Delete Atlassian Bamboo CI service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/bamboo
```
### Get Atlassian Bamboo CI service settings
Get Atlassian Bamboo CI service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/bamboo
```
2018-03-17 18:26:18 +05:30
## Bugzilla
Bugzilla Issue Tracker
2019-02-15 15:39:39 +05:30
### Create/Edit Bugzilla service
2018-03-17 18:26:18 +05:30
Set Bugzilla service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
PUT /projects/:id/services/bugzilla
```
Parameters:
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-05-24 23:13:21 +05:30
| `new_issue_url` | string | true | New Issue URL |
| `issues_url` | string | true | Issue URL |
| `project_url` | string | true | Project URL |
2018-03-17 18:26:18 +05:30
| `description` | string | false | Description |
| `title` | string | false | Title |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2018-03-17 18:26:18 +05:30
### Delete Bugzilla Service
Delete Bugzilla service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
DELETE /projects/:id/services/bugzilla
```
### Get Bugzilla Service Settings
Get Bugzilla service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /projects/:id/services/bugzilla
```
2015-09-25 12:07:36 +05:30
## Buildkite
Continuous integration and deployments
### Create/Edit Buildkite service
Set Buildkite service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/buildkite
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Buildkite project GitLab token |
2020-10-24 23:57:45 +05:30
| `project_url` | string | true | Pipeline URL. For example, `https://buildkite.com/example/pipeline` |
2021-02-22 17:27:13 +05:30
| `enable_ssl_verification` | boolean | false | DEPRECATED: This parameter has no effect since SSL verification is always enabled |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Buildkite service
Delete Buildkite service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/buildkite
```
### Get Buildkite service settings
Get Buildkite service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/buildkite
```
## Campfire
Simple web-based real-time group chat
### Create/Edit Campfire service
Set Campfire service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/campfire
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Campfire token |
| `subdomain` | string | false | Campfire subdomain |
| `room` | string | false | Campfire room |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Campfire service
Delete Campfire service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/campfire
```
### Get Campfire service settings
Get Campfire service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/campfire
```
2020-01-01 13:55:28 +05:30
## Unify Circuit
Unify Circuit RTC and collaboration tool.
### Create/Edit Unify Circuit service
Set Unify Circuit service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2020-01-01 13:55:28 +05:30
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 |
2021-01-29 00:20:46 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" |
2020-01-01 13:55:28 +05:30
| `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.
2020-04-08 14:13:33 +05:30
```plaintext
2020-01-01 13:55:28 +05:30
DELETE /projects/:id/services/unify-circuit
```
### Get Unify Circuit service settings
Get Unify Circuit service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2020-01-01 13:55:28 +05:30
GET /projects/:id/services/unify-circuit
```
2020-05-24 23:13:21 +05:30
## Webex Teams
Webex Teams collaboration tool.
### Create/Edit Webex Teams service
Set Webex Teams service for a project.
```plaintext
PUT /projects/:id/services/webex-teams
```
Parameters:
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `webhook` | string | true | The Webex Teams webhook. For example, `https://api.ciscospark.com/v1/webhooks/incoming/...`. |
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
2021-01-29 00:20:46 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" |
2020-05-24 23:13:21 +05:30
| `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 Webex Teams service
Delete Webex Teams service for a project.
```plaintext
DELETE /projects/:id/services/webex-teams
```
### Get Webex Teams service settings
Get Webex Teams service settings for a project.
```plaintext
GET /projects/:id/services/webex-teams
```
2015-09-25 12:07:36 +05:30
## Custom Issue Tracker
Custom issue tracker
### Create/Edit Custom Issue Tracker service
Set Custom Issue Tracker service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/custom-issue-tracker
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-05-24 23:13:21 +05:30
| `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 |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Custom Issue Tracker service
Delete Custom Issue Tracker service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/custom-issue-tracker
```
### Get Custom Issue Tracker service settings
Get Custom Issue Tracker service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/custom-issue-tracker
```
## 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.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/drone-ci
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Drone CI project specific token |
2019-02-15 15:39:39 +05:30
| `drone_url` | string | true | `http://drone.example.com` |
2018-03-17 18:26:18 +05:30
| `enable_ssl_verification` | boolean | false | Enable SSL verification |
2019-09-04 21:01:54 +05:30
| `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 |
2015-09-25 12:07:36 +05:30
### Delete Drone CI service
Delete Drone CI service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/drone-ci
```
### Get Drone CI service settings
Get Drone CI service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/drone-ci
```
## 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.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/emails-on-push
```
Parameters:
2018-03-17 18:26:18 +05:30
| 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 |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
2021-02-22 17:27:13 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications are always fired for tag pushes. The default value is "all" |
2015-09-25 12:07:36 +05:30
### Delete Emails on push service
Delete Emails on push service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/emails-on-push
```
### Get Emails on push service settings
Get Emails on push service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/emails-on-push
```
2020-07-28 23:09:34 +05:30
## Confluence service
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220934) in GitLab 13.2.
Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace.
### Create/Edit Confluence service
Set Confluence service for a project.
```plaintext
PUT /projects/:id/services/confluence
```
Parameters:
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `confluence_url` | string | true | The URL of the Confluence Cloud Workspace hosted on atlassian.net. |
### Delete Confluence service
Delete Confluence service for a project.
```plaintext
DELETE /projects/:id/services/confluence
```
### Get Confluence service settings
Get Confluence service settings for a project.
```plaintext
GET /projects/:id/services/confluence
```
2015-09-25 12:07:36 +05:30
## 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.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/external-wiki
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `external_wiki_url` | string | true | The URL of the external Wiki |
2015-09-25 12:07:36 +05:30
### Delete External Wiki service
Delete External Wiki service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/external-wiki
```
### Get External Wiki service settings
Get External Wiki service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/external-wiki
```
## Flowdock
Flowdock is a collaboration web app for technical teams.
### Create/Edit Flowdock service
Set Flowdock service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/flowdock
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | Flowdock Git source token |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Flowdock service
Delete Flowdock service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/flowdock
```
### Get Flowdock service settings
Get Flowdock service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/flowdock
```
2019-12-21 20:55:43 +05:30
## GitHub **(PREMIUM)**
Code collaboration software.
### Create/Edit GitHub service
Set GitHub service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
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.
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
DELETE /projects/:id/services/github
```
### Get GitHub service settings
Get GitHub service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
GET /projects/:id/services/github
```
2018-11-18 11:00:15 +05:30
## Hangouts Chat
2020-10-24 23:57:45 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20290) in GitLab 11.2.
2018-11-18 11:00:15 +05:30
2021-03-08 18:12:59 +05:30
Google Workspace team collaboration tool.
2018-11-18 11:00:15 +05:30
### Create/Edit Hangouts Chat service
Set Hangouts Chat service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-07-07 11:18:12 +05:30
PUT /projects/:id/services/hangouts-chat
2018-11-18 11:00:15 +05:30
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-10-24 23:57:45 +05:30
Specific event parameters (for example, `push_events` flag) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435)
2018-11-18 11:00:15 +05:30
Parameters:
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `webhook` | string | true | The Hangouts Chat webhook. For example, `https://chat.googleapis.com/v1/spaces...`. |
2018-11-18 11:00:15 +05:30
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
2019-12-04 20:38:33 +05:30
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
2021-01-29 00:20:46 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" |
2018-11-18 11:00:15 +05:30
| `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 |
2020-01-01 13:55:28 +05:30
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
2018-11-18 11:00:15 +05:30
| `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.
2020-04-08 14:13:33 +05:30
```plaintext
2019-07-07 11:18:12 +05:30
DELETE /projects/:id/services/hangouts-chat
2018-11-18 11:00:15 +05:30
```
### Get Hangouts Chat service settings
Get Hangouts Chat service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-07-07 11:18:12 +05:30
GET /projects/:id/services/hangouts-chat
2018-11-18 11:00:15 +05:30
```
2015-04-26 12:48:37 +05:30
## HipChat
2015-09-25 12:07:36 +05:30
Private group chat and IM
### Create/Edit HipChat service
2015-04-26 12:48:37 +05:30
2015-09-25 12:07:36 +05:30
Set HipChat service for a project.
2015-04-26 12:48:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2015-04-26 12:48:37 +05:30
PUT /projects/:id/services/hipchat
```
2015-09-25 12:07:36 +05:30
2015-04-26 12:48:37 +05:30
Parameters:
2018-03-17 18:26:18 +05:30
| 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) |
2019-02-15 15:39:39 +05:30
| `server` | string | false | Leave blank for default. For example, `https://hipchat.example.com`. |
2019-09-04 21:01:54 +05:30
| `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 |
2021-01-03 14:25:43 +05:30
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
2019-09-04 21:01:54 +05:30
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
2015-04-26 12:48:37 +05:30
### Delete HipChat service
Delete HipChat service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-04-26 12:48:37 +05:30
DELETE /projects/:id/services/hipchat
```
2015-09-25 12:07:36 +05:30
### Get HipChat service settings
Get HipChat service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/hipchat
```
## 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.
2021-02-22 17:27:13 +05:30
NOTE:
2021-03-11 19:13:27 +05:30
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 [Security analysis of `irker`](http://www.catb.org/~esr/irker/security.html).
2015-09-25 12:07:36 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/irker
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `recipients` | string | true | Recipients/channels separated by whitespaces |
2020-06-23 00:09:42 +05:30
| `default_irc_uri` | string | false | `irc://irc.network.net:6697/` |
2018-03-17 18:26:18 +05:30
| `server_host` | string | false | localhost |
| `server_port` | integer | false | 6659 |
| `colorize_messages` | boolean | false | Colorize messages |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Irker (IRC gateway) service
Delete Irker (IRC gateway) service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/irker
```
### Get Irker (IRC gateway) service settings
Get Irker (IRC gateway) service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/irker
```
2019-09-30 21:07:59 +05:30
## Jira
2015-09-25 12:07:36 +05:30
2019-09-30 21:07:59 +05:30
Jira issue tracker.
2017-01-15 13:20:01 +05:30
2019-09-30 21:07:59 +05:30
### Get Jira service settings
2017-01-15 13:20:01 +05:30
2019-09-30 21:07:59 +05:30
Get Jira service settings for a project.
2017-01-15 13:20:01 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-01-15 13:20:01 +05:30
GET /projects/:id/services/jira
```
2015-09-25 12:07:36 +05:30
2019-09-30 21:07:59 +05:30
### Create/Edit Jira service
2015-09-25 12:07:36 +05:30
2019-09-30 21:07:59 +05:30
Set Jira service for a project.
2015-09-25 12:07:36 +05:30
2019-07-07 11:18:12 +05:30
> Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and
2019-07-31 22:56:46 +05:30
> `project_url` are replaced by `url`. If you are using an
2019-12-26 22:10:19 +05:30
> older version, [follow this documentation](https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable-ee/doc/api/services.md#jira).
2015-09-25 12:07:36 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/jira
```
2018-03-17 18:26:18 +05:30
Parameters:
| Parameter | Type | Required | Description |
2017-01-15 13:20:01 +05:30
| --------- | ---- | -------- | ----------- |
2019-09-30 21:07:59 +05:30
| `url` | string | yes | The URL to the Jira project which is being linked to this GitLab project. For example, `https://jira.example.com`. |
2021-02-22 17:27:13 +05:30
| `api_url` | string | no | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. |
2019-09-30 21:07:59 +05:30
| `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. |
2019-07-07 11:18:12 +05:30
| `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). |
2020-11-24 15:15:51 +05:30
| `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`. |
2019-09-04 21:01:54 +05:30
| `commit_events` | boolean | false | Enable notifications for commit events |
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
2020-03-13 15:44:24 +05:30
| `comment_on_event_enabled` | boolean | false | Enable comments inside Jira issues on each GitLab event (commit / merge request) |
2015-09-25 12:07:36 +05:30
2019-09-30 21:07:59 +05:30
### Delete Jira service
2015-09-25 12:07:36 +05:30
2019-09-30 21:07:59 +05:30
Remove all previously Jira settings from a project.
2015-09-25 12:07:36 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/jira
```
2017-08-17 22:00:37 +05:30
## Slack slash commands
Ability to receive slash commands from a Slack chat instance.
### Get Slack slash command service settings
Get Slack slash command service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/services/slack-slash-commands
```
Example response:
```json
{
"id": 4,
"title": "Slack slash commands",
2020-03-13 15:44:24 +05:30
"slug": "slack-slash-commands",
2017-08-17 22:00:37 +05:30
"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,
2018-03-27 19:54:05 +05:30
"confidential_issues_events": true,
2017-08-17 22:00:37 +05:30
"merge_requests_events": true,
"tag_push_events": true,
"note_events": true,
2017-09-10 17:25:29 +05:30
"job_events": true,
2017-08-17 22:00:37 +05:30
"pipeline_events": true,
2020-03-13 15:44:24 +05:30
"comment_on_event_enabled": false,
2017-08-17 22:00:37 +05:30
"properties": {
2019-02-15 15:39:39 +05:30
"token": "<your_access_token>"
2017-08-17 22:00:37 +05:30
}
}
```
### Create/Edit Slack slash command service
Set Slack slash command for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/services/slack-slash-commands
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
2017-08-17 22:00:37 +05:30
| --------- | ---- | -------- | ----------- |
| `token` | string | yes | The Slack token |
### Delete Slack slash command service
Delete Slack slash command service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/services/slack-slash-commands
```
## Mattermost slash commands
Ability to receive slash commands from a Mattermost chat instance.
### Get Mattermost slash command service settings
Get Mattermost slash command service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/services/mattermost-slash-commands
```
### Create/Edit Mattermost slash command service
Set Mattermost slash command for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/services/mattermost-slash-commands
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
2017-08-17 22:00:37 +05:30
| --------- | ---- | -------- | ----------- |
| `token` | string | yes | The Mattermost token |
2018-03-17 18:26:18 +05:30
| `username` | string | no | The username to use to post the message |
2017-08-17 22:00:37 +05:30
### Delete Mattermost slash command service
Delete Mattermost slash command service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/services/mattermost-slash-commands
```
2018-03-17 18:26:18 +05:30
## Packagist
2020-04-08 14:13:33 +05:30
Update your project on Packagist (the main Composer repository) when commits or tags are pushed to GitLab.
2018-03-17 18:26:18 +05:30
### Create/Edit Packagist service
Set Packagist service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
PUT /projects/:id/services/packagist
```
Parameters:
2019-09-04 21:01:54 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `username` | string | yes | The username of a Packagist account |
| `token` | string | yes | API token to the Packagist server |
2019-09-30 21:07:59 +05:30
| `server` | boolean | no | URL of the Packagist server. Leave blank for default: <https://packagist.org> |
2019-09-04 21:01:54 +05:30
| `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 |
2018-03-17 18:26:18 +05:30
### Delete Packagist service
Delete Packagist service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
DELETE /projects/:id/services/packagist
```
### Get Packagist service settings
Get Packagist service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /projects/:id/services/packagist
```
2017-08-17 22:00:37 +05:30
## Pipeline-Emails
2020-04-22 19:07:51 +05:30
Get emails for GitLab CI/CD pipelines.
2017-08-17 22:00:37 +05:30
### Create/Edit Pipeline-Emails service
Set Pipeline-Emails service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/services/pipelines-email
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
2017-08-17 22:00:37 +05:30
| --------- | ---- | -------- | ----------- |
| `recipients` | string | yes | Comma-separated list of recipient email addresses |
| `add_pusher` | boolean | no | Add pusher to recipients list |
| `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines |
2021-01-29 00:20:46 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected. The default value is "default" |
2020-03-13 15:44:24 +05:30
| `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)) |
2019-09-04 21:01:54 +05:30
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
2017-08-17 22:00:37 +05:30
### Delete Pipeline-Emails service
Delete Pipeline-Emails service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/services/pipelines-email
```
### Get Pipeline-Emails service settings
Get Pipeline-Emails service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/services/pipelines-email
```
2015-09-25 12:07:36 +05:30
## PivotalTracker
Project Management Software (Source Commits Endpoint)
### Create/Edit PivotalTracker service
Set PivotalTracker service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/pivotaltracker
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `token` | string | true | The PivotalTracker token |
2021-02-22 17:27:13 +05:30
| `restrict_to_branch` | boolean | false | Comma-separated list of branches to automatically inspect. Leave blank to include all branches. |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete PivotalTracker service
Delete PivotalTracker service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/pivotaltracker
```
### Get PivotalTracker service settings
Get PivotalTracker service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/pivotaltracker
```
2018-03-17 18:26:18 +05:30
## Prometheus
Prometheus is a powerful time-series monitoring service.
### Create/Edit Prometheus service
Set Prometheus service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
PUT /projects/:id/services/prometheus
```
Parameters:
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `api_url` | string | true | Prometheus API Base URL. For example, `http://prometheus.example.com/`. |
2020-06-23 00:09:42 +05:30
| `google_iap_audience_client_id` | string | false | Client ID of the IAP secured resource (looks like IAP_CLIENT_ID.apps.googleusercontent.com) |
2020-07-28 23:09:34 +05:30
| `google_iap_service_account_json` | string | false | `credentials.json` file for your service account, like { "type": "service_account", "project_id": ... } |
2018-03-17 18:26:18 +05:30
### Delete Prometheus service
Delete Prometheus service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
DELETE /projects/:id/services/prometheus
```
### Get Prometheus service settings
Get Prometheus service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /projects/:id/services/prometheus
```
2015-09-25 12:07:36 +05:30
## 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.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/pushover
```
Parameters:
2018-03-17 18:26:18 +05:30
| 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 |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Pushover service
Delete Pushover service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/pushover
```
### Get Pushover service settings
Get Pushover service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/pushover
```
## Redmine
Redmine issue tracker
### Create/Edit Redmine service
Set Redmine service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/redmine
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-05-24 23:13:21 +05:30
| `new_issue_url` | string | true | New Issue URL |
| `project_url` | string | true | Project URL |
| `issues_url` | string | true | Issue URL |
2018-03-17 18:26:18 +05:30
| `description` | string | false | Description |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete Redmine service
Delete Redmine service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/redmine
```
### Get Redmine service settings
Get Redmine service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/redmine
```
2017-08-17 22:00:37 +05:30
## Slack notifications
2015-09-25 12:07:36 +05:30
2017-08-17 22:00:37 +05:30
Receive event notifications in Slack
2015-09-25 12:07:36 +05:30
### Create/Edit Slack service
Set Slack service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/slack
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-10-24 23:57:45 +05:30
Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435)
2018-03-17 18:26:18 +05:30
2015-09-25 12:07:36 +05:30
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `webhook` | string | true | `https://hooks.slack.com/services/...` |
2018-03-17 18:26:18 +05:30
| `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 |
2019-12-04 20:38:33 +05:30
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
2021-01-29 00:20:46 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" |
2019-10-12 21:52:04 +05:30
| `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 |
2018-03-17 18:26:18 +05:30
| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
2019-10-12 21:52:04 +05:30
| `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 |
2018-03-17 18:26:18 +05:30
| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
2019-10-12 21:52:04 +05:30
| `note_channel` | string | false | The name of the channel to receive note events notifications |
2018-03-17 18:26:18 +05:30
| `note_events` | boolean | false | Enable notifications for note events |
2019-10-12 21:52:04 +05:30
| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications |
2018-03-17 18:26:18 +05:30
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
| `push_channel` | string | false | The name of the channel to receive push events notifications |
2019-10-12 21:52:04 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2018-03-17 18:26:18 +05:30
| `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications |
2019-10-12 21:52:04 +05:30
| `tag_push_events` | boolean | false | Enable notifications for tag push events |
2018-03-17 18:26:18 +05:30
| `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications |
2019-10-12 21:52:04 +05:30
| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
2015-09-25 12:07:36 +05:30
### Delete Slack service
Delete Slack service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/slack
```
### Get Slack service settings
Get Slack service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/slack
```
2018-03-17 18:26:18 +05:30
## Microsoft Teams
Group Chat Software
### Create/Edit Microsoft Teams service
Set Microsoft Teams service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
PUT /projects/:id/services/microsoft-teams
2018-03-17 18:26:18 +05:30
```
Parameters:
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `webhook` | string | true | The Microsoft Teams webhook. For example, `https://outlook.office.com/webhook/...` |
2019-09-04 21:01:54 +05:30
| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
2019-12-04 20:38:33 +05:30
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
2021-01-29 00:20:46 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" |
2019-09-04 21:01:54 +05:30
| `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 |
2020-04-08 14:13:33 +05:30
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
2019-09-04 21:01:54 +05:30
| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
2018-03-17 18:26:18 +05:30
### Delete Microsoft Teams service
Delete Microsoft Teams service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
DELETE /projects/:id/services/microsoft-teams
2018-03-17 18:26:18 +05:30
```
### Get Microsoft Teams service settings
Get Microsoft Teams service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
GET /projects/:id/services/microsoft-teams
2018-03-17 18:26:18 +05:30
```
2017-08-17 22:00:37 +05:30
## Mattermost notifications
Receive event notifications in Mattermost
### Create/Edit Mattermost notifications service
Set Mattermost service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/services/mattermost
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-10-24 23:57:45 +05:30
Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435)
2018-03-17 18:26:18 +05:30
2017-08-17 22:00:37 +05:30
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `webhook` | string | true | The Mattermost webhook. For example, `http://mattermost_host/hooks/...` |
2018-03-17 18:26:18 +05:30
| `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 |
2019-12-04 20:38:33 +05:30
| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` |
2021-01-29 00:20:46 +05:30
| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" |
2018-03-17 18:26:18 +05:30
| `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 |
2020-01-01 13:55:28 +05:30
| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
2018-03-17 18:26:18 +05:30
| `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 |
2020-01-01 13:55:28 +05:30
| `confidential_note_channel` | boolean | The name of the channel to receive confidential note events notifications |
2018-03-17 18:26:18 +05:30
| `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 |
2017-08-17 22:00:37 +05:30
### Delete Mattermost notifications service
Delete Mattermost Notifications service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/services/mattermost
```
### Get Mattermost notifications service settings
Get Mattermost notifications service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/services/mattermost
```
2015-09-25 12:07:36 +05:30
## JetBrains TeamCity CI
A continuous integration and build server
### Create/Edit JetBrains TeamCity CI service
Set JetBrains TeamCity CI service for a project.
2021-02-22 17:27:13 +05:30
> The build configuration in TeamCity must use the build format number `%build.vcs.number%`. Configure monitoring of all branches so merge requests build. That setting is in the VSC root advanced settings.
2015-09-25 12:07:36 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
PUT /projects/:id/services/teamcity
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `teamcity_url` | string | true | TeamCity root URL. For example, `https://teamcity.example.com` |
2018-03-17 18:26:18 +05:30
| `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 |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2015-09-25 12:07:36 +05:30
### Delete JetBrains TeamCity CI service
Delete JetBrains TeamCity CI service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
DELETE /projects/:id/services/teamcity
```
### Get JetBrains TeamCity CI service settings
Get JetBrains TeamCity CI service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2015-09-25 12:07:36 +05:30
GET /projects/:id/services/teamcity
```
2017-01-15 13:20:01 +05:30
2021-03-11 19:13:27 +05:30
## Jenkins CI
2019-09-04 21:01:54 +05:30
A continuous integration and build server
### Create/Edit Jenkins CI service
Set Jenkins CI service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
PUT /projects/:id/services/jenkins
```
Parameters:
2019-09-30 21:07:59 +05:30
- `jenkins_url` (**required**) - Jenkins URL like `http://jenkins.example.com`
2019-09-04 21:01:54 +05:30
- `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.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
DELETE /projects/:id/services/jenkins
```
### Get Jenkins CI service settings
Get Jenkins CI service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /projects/:id/services/jenkins
```
## Jenkins CI (Deprecated) Service
A continuous integration and build server
2021-02-22 17:27:13 +05:30
NOTE:
2020-05-24 23:13:21 +05:30
This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600)
2019-09-04 21:01:54 +05:30
### Create/Edit Jenkins CI (Deprecated) service
Set Jenkins CI (Deprecated) service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
PUT /projects/:id/services/jenkins-deprecated
```
Parameters:
2019-09-30 21:07:59 +05:30
- `project_url` (**required**) - Jenkins project URL like `http://jenkins.example.com/job/my-project/`
2019-09-04 21:01:54 +05:30
- `multiproject_enabled` (optional) - Multi-project mode is configured in Jenkins GitLab Hook plugin
2021-02-22 17:27:13 +05:30
- `pass_unstable` (optional) - Unstable builds are treated as passing
2019-09-04 21:01:54 +05:30
### Delete Jenkins CI (Deprecated) service
Delete Jenkins CI (Deprecated) service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
DELETE /projects/:id/services/jenkins-deprecated
```
### Get Jenkins CI (Deprecated) service settings
Get Jenkins CI (Deprecated) service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /projects/:id/services/jenkins-deprecated
```
2017-08-17 22:00:37 +05:30
## 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.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/services/mock-ci
```
Parameters:
2018-03-17 18:26:18 +05:30
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2019-02-15 15:39:39 +05:30
| `mock_service_url` | string | true | `http://localhost:4004` |
2017-08-17 22:00:37 +05:30
### Delete MockCI service
Delete MockCI service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/services/mock-ci
```
### Get MockCI service settings
Get MockCI service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/services/mock-ci
```
2018-03-17 18:26:18 +05:30
2019-07-07 11:18:12 +05:30
## YouTrack
YouTrack issue tracker
### Create/Edit YouTrack service
Set YouTrack service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-07-07 11:18:12 +05:30
PUT /projects/:id/services/youtrack
```
Parameters:
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-05-24 23:13:21 +05:30
| `issues_url` | string | true | Issue URL |
| `project_url` | string | true | Project URL |
2019-07-07 11:18:12 +05:30
| `description` | string | false | Description |
2019-09-04 21:01:54 +05:30
| `push_events` | boolean | false | Enable notifications for push events |
2019-07-07 11:18:12 +05:30
### Delete YouTrack Service
Delete YouTrack service for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-07-07 11:18:12 +05:30
DELETE /projects/:id/services/youtrack
```
### Get YouTrack Service Settings
Get YouTrack service settings for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2019-07-07 11:18:12 +05:30
GET /projects/:id/services/youtrack
```