Commit 507abdb7 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs/fix-webhooks-headings' into 'master'

Small refactor of webhooks docs

See merge request !7872
parents 42dc2033 bc8b6024
doc/web_hooks/ssl.png

22.6 KB | W: | H:

doc/web_hooks/ssl.png

27.1 KB | W: | H:

doc/web_hooks/ssl.png
doc/web_hooks/ssl.png
doc/web_hooks/ssl.png
doc/web_hooks/ssl.png
  • 2-up
  • Swipe
  • Onion skin
# 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: ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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: ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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.
...@@ -754,7 +764,7 @@ X-Gitlab-Event: Wiki Page Hook ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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>}
......
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