Skip to content

G
gitlab-ce
Commit e664b5c3 authored by Kati Paizee's avatar Kati Paizee Committed by Suzanne Selhorn
Browse files
Options

CTRT edits for webhooks - part 4

parent 2814653e
Show whitespace changes
Inline Side-by-side
Showing with 133 additions and 116 deletions
doc/user/project/integrations/webhook_events.md
View file @ e664b5c3
...@@ -9,31 +9,45 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -9,31 +9,45 @@ info: To determine the technical writer assigned to the Stage/Group associated w
You can configure a [webhook](webhooks.md) in your project that triggers when You can configure a [webhook](webhooks.md) in your project that triggers when
an event occurs. The following events are supported. an event occurs. The following events are supported.
Event type | Trigger
---------------------------------------------|-----------------------------------------------------------------------------
[Push event](#push-events) | A push is made to the repository.
[Tag event](#tag-events) | Tags are created or deleted in the repository.
[Issue event](#issue-events) | A new issue is created or an existing issue is updated, closed, or reopened.
[Comment event](#comment-events) | A new comment is made on commits, merge requests, issues, and code snippets.
[Merge request event](#merge-request-events) | A merge request is created, updated, merged, or closed, or a commit is added in the source branch.
[Wiki page event](#wiki-page-events) | A wiki page is created, updated, or deleted.
[Pipeline event](#pipeline-events) | A pipeline status changes.
[Job event](#job-events) | A job status changes.
[Deployment event](#deployment-events) | A deployment starts, succeeds, fails, or is canceled.
[Group member event](#group-member-events) | A user is added or removed from a group, or a user's access level or access expiration date changes.
[Subgroup event](#subgroup-events) | A subgroup is created or removed from a group.
[Feature flag event](#feature-flag-events) | A feature flag is turned on or off.
[Release event](#release-events) | A release is created or updated.
## Push events ## Push events
Triggered when you push to the repository except when pushing tags. Push events are triggered when you push to the repository, except when:
NOTE: - You push tags.
When more than 20 commits are pushed at once, the `commits` webhook - A single push includes changes for more than three branches by default
attribute only contains the newest 20 for performance reasons. Loading (depending on the [`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)).
detailed commit data is expensive. Note that despite only 20 commits being
present in the `commits` attribute, the `total_commits_count` attribute contains the actual total.
NOTE: If you push more than 20 commits at once, the `commits`
If a branch creation push event is generated without new commits being introduced, the attribute in the payload contains information about the newest 20 commits only.
`commits` attribute in the payload is empty. Loading detailed commit data is expensive, so this restriction exists for performance reasons.
The `total_commits_count` attribute contains the actual number of commits.
Also, if a single push includes changes for more than three (by default, depending on If you create and push a branch without any new commits, the
[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) `commits` attribute in the payload is empty.
branches, this hook isn't executed.
**Request header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Push Hook X-Gitlab-Event: Push Hook
``` ```
**Payload example:** Payload example:
```json ```json
{ {
...@@ -111,20 +125,19 @@ X-Gitlab-Event: Push Hook ...@@ -111,20 +125,19 @@ X-Gitlab-Event: Push Hook
## Tag events ## Tag events
Triggered when you create (or delete) tags to the repository. Tag events are triggered when you create or delete tags in the repository.
NOTE: This hook is not executed if a single push includes changes for more than three
If a single push includes changes for more than three (by default, depending on tags by default (depending on the
[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) [`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)).
tags, this hook is not executed.
**Request header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Tag Push Hook X-Gitlab-Event: Tag Push Hook
``` ```
**Payload example:** Payload example:
```json ```json
{ {
...@@ -171,22 +184,26 @@ X-Gitlab-Event: Tag Push Hook ...@@ -171,22 +184,26 @@ X-Gitlab-Event: Tag Push Hook
## Issue events ## Issue events
Triggered when a new issue is created or an existing issue was updated/closed/reopened. Issue events are triggered when a new issue is created or
an existing issue is updated, closed, or reopened.
**Request header**:
```plaintext
X-Gitlab-Event: Issue Hook
```
**Available `object_attributes.action`:** The available values for `object_attributes.action` in the payload are:
- `open` - `open`
- `close` - `close`
- `reopen` - `reopen`
- `update` - `update`
**Payload example:** The `assignee` and `assignee_id` keys are deprecated
and contain the first assignee only.
Request header:
```plaintext
X-Gitlab-Event: Issue Hook
```
Payload example:
```json ```json
{ {
...@@ -329,31 +346,31 @@ X-Gitlab-Event: Issue Hook ...@@ -329,31 +346,31 @@ X-Gitlab-Event: Issue Hook
} }
``` ```
NOTE:
`assignee` and `assignee_id` keys are deprecated and now show the first assignee only.
## Comment events ## Comment events
Triggered when a new comment is made on commits, merge requests, issues, and code snippets. Comment events are triggered when a new comment is made on commits,
The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The merge requests, issues, and code snippets.
payload also includes information about the target of the comment. For example,
a comment on an issue includes the specific issue information under the `issue` key. The note data is stored in `object_attributes` (for example, `note` or `noteable_type`).
Valid target types: The payload includes information about the target of the comment. For example,
a comment on an issue includes specific issue information under the `issue` key.
The valid target types are:
- `commit` - `commit`
- `merge_request` - `merge_request`
- `issue` - `issue`
- `snippet` - `snippet`
### Comment on commit ### Comment on a commit
**Request header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Note Hook X-Gitlab-Event: Note Hook
``` ```
**Payload example:** Payload example:
```json ```json
{ {
...@@ -428,15 +445,15 @@ X-Gitlab-Event: Note Hook ...@@ -428,15 +445,15 @@ X-Gitlab-Event: Note Hook
} }
``` ```
### Comment on merge request ### Comment on a merge request
**Request header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Note Hook X-Gitlab-Event: Note Hook
``` ```
**Payload example:** Payload example:
```json ```json
{ {
...@@ -558,15 +575,18 @@ X-Gitlab-Event: Note Hook ...@@ -558,15 +575,18 @@ X-Gitlab-Event: Note Hook
} }
``` ```
### Comment on issue ### Comment on an issue
- The `assignee_id` field is deprecated and shows the first assignee only.
- The `event_type` is set to `confidential_note` for confidential issues.
**Request header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Note Hook X-Gitlab-Event: Note Hook
``` ```
**Payload example:** Payload example:
```json ```json
{ {
...@@ -664,21 +684,15 @@ X-Gitlab-Event: Note Hook ...@@ -664,21 +684,15 @@ X-Gitlab-Event: Note Hook
} }
``` ```
NOTE: ### Comment on a code snippet
`assignee_id` field is deprecated and now shows the first assignee only.
NOTE: Request header:
`event_type` is set to `confidential_note` for confidential issues.
### Comment on code snippet
**Request header**:
```plaintext ```plaintext
X-Gitlab-Event: Note Hook X-Gitlab-Event: Note Hook
``` ```
**Payload example:** Payload example:
```json ```json
{ {
...@@ -749,15 +763,13 @@ X-Gitlab-Event: Note Hook ...@@ -749,15 +763,13 @@ X-Gitlab-Event: Note Hook
## Merge request events ## Merge request events
Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch. Merge request events are triggered when:
**Request header**: - A new merge request is created.
- An existing merge request is updated, merged, or closed.
- A commit is added in the source branch.
```plaintext The available values for `object_attributes.action` in the payload are:
X-Gitlab-Event: Merge Request Hook
```
**Available `object_attributes.action`:**
- `open` - `open`
- `close` - `close`
...@@ -767,7 +779,13 @@ X-Gitlab-Event: Merge Request Hook ...@@ -767,7 +779,13 @@ X-Gitlab-Event: Merge Request Hook
- `unapproved` - `unapproved`
- `merge` - `merge`
**Payload example:** Request header:
```plaintext
X-Gitlab-Event: Merge Request Hook
```
Payload example:
```json ```json
{ {
...@@ -921,17 +939,17 @@ X-Gitlab-Event: Merge Request Hook ...@@ -921,17 +939,17 @@ X-Gitlab-Event: Merge Request Hook
} }
``` ```
## Wiki Page events ## Wiki page events
Triggered when a wiki page is created, updated or deleted. Wiki page events are triggered when a wiki page is created, updated, or deleted.
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Wiki Page Hook X-Gitlab-Event: Wiki Page Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -981,18 +999,18 @@ X-Gitlab-Event: Wiki Page Hook ...@@ -981,18 +999,18 @@ X-Gitlab-Event: Wiki Page Hook
## Pipeline events ## Pipeline events
Pipeline events are triggered when the status of a pipeline changes.
In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159)
and later, the pipeline webhook returns only the latest jobs. and later, the pipeline webhook returns only the latest jobs.
Triggered on status change of Pipeline. Request header:
**Request Header**:
```plaintext ```plaintext
X-Gitlab-Event: Pipeline Hook X-Gitlab-Event: Pipeline Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1233,15 +1251,17 @@ X-Gitlab-Event: Pipeline Hook ...@@ -1233,15 +1251,17 @@ X-Gitlab-Event: Pipeline Hook
## Job events ## Job events
Triggered on status change of a job. Job events are triggered when the status of a job changes.
The `commit.id` in the payload is the ID of the pipeline, not the ID of the commit.
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Job Hook X-Gitlab-Event: Job Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1303,24 +1323,24 @@ X-Gitlab-Event: Job Hook ...@@ -1303,24 +1323,24 @@ X-Gitlab-Event: Job Hook
} }
``` ```
Note that `commit.id` is the ID of the pipeline, not the ID of the commit.
## Deployment events ## Deployment events
Triggered when a deployment: Deployment events are triggered when a deployment:
- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) - Starts ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5)
- Succeeds - Succeeds
- Fails - Fails
- Is cancelled - Is cancelled
**Request Header**: The `deployable_id` in the payload is the ID of the CI/CD job.
Request header:
```plaintext ```plaintext
X-Gitlab-Event: Deployment Hook X-Gitlab-Event: Deployment Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1363,28 +1383,26 @@ X-Gitlab-Event: Deployment Hook ...@@ -1363,28 +1383,26 @@ X-Gitlab-Event: Deployment Hook
} }
``` ```
Note that `deployable_id` is the ID of the CI job.
## Group member events **(PREMIUM)** ## Group member events **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7.
Member events are triggered when: Member events are triggered when:
- A user is added as a group member - A user is added as a group member.
- The access level of a user has changed - The access level of a user changes.
- The expiration date for user access has been updated - The expiration date for user access is updated.
- A user has been removed from the group - A user is removed from the group.
### Add member to group ### Add member to group
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Member Hook X-Gitlab-Event: Member Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1406,13 +1424,13 @@ X-Gitlab-Event: Member Hook ...@@ -1406,13 +1424,13 @@ X-Gitlab-Event: Member Hook
### Update member access level or expiration date ### Update member access level or expiration date
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Member Hook X-Gitlab-Event: Member Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1434,13 +1452,13 @@ X-Gitlab-Event: Member Hook ...@@ -1434,13 +1452,13 @@ X-Gitlab-Event: Member Hook
### Remove member from group ### Remove member from group
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Member Hook X-Gitlab-Event: Member Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1466,18 +1484,18 @@ X-Gitlab-Event: Member Hook ...@@ -1466,18 +1484,18 @@ X-Gitlab-Event: Member Hook
Subgroup events are triggered when: Subgroup events are triggered when:
- A [subgroup is created in a group](#subgroup-created-in-a-group) - A [subgroup is created in a group](#create-a-subgroup-in-a-group).
- A [subgroup is removed from a group](#subgroup-removed-from-a-group) - A [subgroup is removed from a group](#remove-a-subgroup-from-a-group).
### Subgroup created in a group ### Create a subgroup in a group
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Subgroup Hook X-Gitlab-Event: Subgroup Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1497,15 +1515,17 @@ X-Gitlab-Event: Subgroup Hook ...@@ -1497,15 +1515,17 @@ X-Gitlab-Event: Subgroup Hook
} }
``` ```
### Subgroup removed from a group ### Remove a subgroup from a group
This webhook is not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group).
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Subgroup Hook X-Gitlab-Event: Subgroup Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1525,20 +1545,17 @@ X-Gitlab-Event: Subgroup Hook ...@@ -1525,20 +1545,17 @@ X-Gitlab-Event: Subgroup Hook
} }
``` ```
NOTE: ## Feature flag events
Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group)
## Feature Flag events
Triggered when a feature flag is turned on or off. Feature flag events are triggered when a feature flag is turned on or off.
**Request Header**: Request header:
```plaintext ```plaintext
X-Gitlab-Event: Feature Flag Hook X-Gitlab-Event: Feature Flag Hook
``` ```
**Payload example**: Payload example:
```json ```json
{ {
...@@ -1580,20 +1597,20 @@ X-Gitlab-Event: Feature Flag Hook ...@@ -1580,20 +1597,20 @@ X-Gitlab-Event: Feature Flag Hook
## Release events ## Release events
Triggered when a release is created or updated. Release events are triggered when a release is created or updated.
**Request Header**: The available values for `object_attributes.action` in the payload are:
- `create`
- `update`
Request header:
```plaintext ```plaintext
X-Gitlab-Event: Release Hook X-Gitlab-Event: Release Hook
``` ```
**Available `object_attributes.action`:** Payload example:
- `create`
- `update`
**Payload example**:
```json ```json
{ {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7