kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Small refactor of webhooks docs

Browse source 
[ci skip]
This commit is contained in:
Achilleas Pipinellis 2016-12-01 13:19:00 +01:00
parent 42dc2033dd
commit bc8b6024b1
2 changed files with 46 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
doc/web_hooks/ssl.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 27 KiB

81
doc/web_hooks/web_hooks.md
View file

@ -1,17 +1,21 @@
# Webhooks # Webhooks
_**Note:** >**Note:**
Starting from GitLab 8.5:_ Starting from GitLab 8.5:
- the `repository` key is deprecated in favor of the `project` key
- the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key
- the `project.http_url` key is deprecated in favor of the `project.git_http_url` key
- _the `repository` key is deprecated in favor of the `project` key_ Project webhooks allow you to trigger a URL if for example new code is pushed or
- _the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key_ a new issue is created. You can configure webhooks to listen for specific events
- _the `project.http_url` key is deprecated in favor of the `project.git_http_url` key_ like pushes, issues or merge requests. GitLab will send a POST request with data
to the webhook URL.
Project webhooks allow you to trigger an URL if new code is pushed or a new issue is created. Webhooks can be used to update an external issue tracker, trigger CI builds,
update a backup mirror, or even deploy to your production server.
You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the webhook URL. Navigate to the webhooks page by choosing **Webhooks** from your project's
settings which can be found under the wheel icon in the upper right corner.
Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server.
## Webhook endpoint tips ## Webhook endpoint tips
@ -26,21 +30,27 @@ GitLab webhooks keep in mind the following things:
you are writing a low-level hook this is important to remember. you are writing a low-level hook this is important to remember.
- GitLab ignores the HTTP status code returned by your endpoint. - GitLab ignores the HTTP status code returned by your endpoint.
## Secret Token ## Secret token
If you specify a secret token, it will be sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate. If you specify a secret token, it will be sent with the hook request in the
`X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify
that the request is legitimate.
## SSL Verification ## SSL verification
By default, the SSL certificate of the webhook endpoint is verified based on By default, the SSL certificate of the webhook endpoint is verified based on
an internal list of Certificate Authorities, an internal list of Certificate Authorities, which means the certificate cannot
which means the certificate cannot be self-signed. be self-signed.
You can turn this off in the webhook settings in your GitLab projects. You can turn this off in the webhook settings in your GitLab projects.
![SSL Verification](ssl.png) ![SSL Verification](ssl.png)
## Push events ## Events
Below are described the supported events.
### Push events
Triggered when you push to the repository except when pushing tags. Triggered when you push to the repository except when pushing tags.
@ -121,7 +131,7 @@ X-Gitlab-Event: Push Hook
} }
``` ```
## Tag events ### Tag events
Triggered when you create (or delete) tags to the repository. Triggered when you create (or delete) tags to the repository.
@ -174,7 +184,7 @@ X-Gitlab-Event: Tag Push Hook
} }
``` ```
## Issues events ### Issues events
Triggered when a new issue is created or an existing issue was updated/closed/reopened. Triggered when a new issue is created or an existing issue was updated/closed/reopened.
@ -240,7 +250,7 @@ X-Gitlab-Event: Issue Hook
} }
} }
``` ```
## Comment events ### Comment events
Triggered when a new comment is made on commits, merge requests, issues, and code snippets. Triggered when a new comment is made on commits, merge requests, issues, and code snippets.
The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The
@ -253,7 +263,7 @@ Valid target types:
3. `issue` 3. `issue`
4. `snippet` 4. `snippet`
### Comment on commit #### Comment on commit
**Request header**: **Request header**:
@ -332,7 +342,7 @@ X-Gitlab-Event: Note Hook
} }
``` ```
### Comment on merge request #### Comment on merge request
**Request header**: **Request header**:
@ -459,7 +469,7 @@ X-Gitlab-Event: Note Hook
} }
``` ```
### Comment on issue #### Comment on issue
**Request header**: **Request header**:
@ -534,7 +544,7 @@ X-Gitlab-Event: Note Hook
} }
``` ```
### Comment on code snippet #### Comment on code snippet
**Request header**: **Request header**:
@ -607,7 +617,7 @@ 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. 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.
@ -699,7 +709,7 @@ X-Gitlab-Event: Merge Request Hook
} }
``` ```
## Wiki Page events ### Wiki Page events
Triggered when a wiki page is created or edited. Triggered when a wiki page is created or edited.
@ -737,9 +747,9 @@ X-Gitlab-Event: Wiki Page Hook
}, },
"wiki": { "wiki": {
"web_url": "http://example.com/root/awesome-project/wikis/home", "web_url": "http://example.com/root/awesome-project/wikis/home",
"git_ssh_url": "git@example.com:root/awesome-project.wiki.git", "git_ssh_url": "git@example.com:root/awesome-project.wiki.git",
"git_http_url": "http://example.com/root/awesome-project.wiki.git", "git_http_url": "http://example.com/root/awesome-project.wiki.git",
"path_with_namespace": "root/awesome-project.wiki", "path_with_namespace": "root/awesome-project.wiki",
"default_branch": "master" "default_branch": "master"
}, },
"object_attributes": { "object_attributes": {
@ -754,7 +764,7 @@ X-Gitlab-Event: Wiki Page Hook
} }
``` ```
## Pipeline events ### Pipeline events
Triggered on status change of Pipeline. Triggered on status change of Pipeline.
@ -922,8 +932,7 @@ X-Gitlab-Event: Pipeline Hook
} }
``` ```
### Build events
## Build events
Triggered on status change of a Build. Triggered on status change of a Build.
@ -935,7 +944,7 @@ X-Gitlab-Event: Build Hook
**Request Body**: **Request Body**:
``` ```json
{ {
"object_kind": "build", "object_kind": "build",
"ref": "gitlab-script-trigger", "ref": "gitlab-script-trigger",
@ -980,12 +989,13 @@ X-Gitlab-Event: Build Hook
} }
``` ```
#### Example webhook receiver ## Example webhook receiver
If you want to see GitLab's webhooks in action for testing purposes you can use If you want to see GitLab's webhooks in action for testing purposes you can use
a simple echo script running in a console session. a simple echo script running in a console session. For the following script to
work you need to have Ruby installed.
Save the following file as `print_http_body.rb`. Save the following file as `print_http_body.rb`:
```ruby ```ruby
require 'webrick' require 'webrick'
@ -1005,7 +1015,8 @@ Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb
8000`. Then add your server as a webhook receiver in GitLab as 8000`. Then add your server as a webhook receiver in GitLab as
`http://my.host:8000/`. `http://my.host:8000/`.
When you press 'Test Hook' in GitLab, you should see something like this in the console. When you press 'Test Hook' in GitLab, you should see something like this in the
console:
``` ```
{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>} {"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}