From bc8b6024b1a993f4f2ba673e542a02395ba691a0 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 1 Dec 2016 13:19:00 +0100 Subject: Small refactor of webhooks docs [ci skip] --- doc/web_hooks/ssl.png | Bin 23191 -> 27799 bytes doc/web_hooks/web_hooks.md | 81 +++++++++++++++++++++++++-------------------- 2 files changed, 46 insertions(+), 35 deletions(-) (limited to 'doc/web_hooks') diff --git a/doc/web_hooks/ssl.png b/doc/web_hooks/ssl.png index a552888ed96..21ddec4ebdf 100644 Binary files a/doc/web_hooks/ssl.png and b/doc/web_hooks/ssl.png differ diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md index cd37189fdd2..1659dd1f6cb 100644 --- a/doc/web_hooks/web_hooks.md +++ b/doc/web_hooks/web_hooks.md @@ -1,17 +1,21 @@ # Webhooks -_**Note:** -Starting from GitLab 8.5:_ +>**Note:** +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_ -- _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_ +Project webhooks allow you to trigger a URL if for example new code is pushed or +a new issue is created. 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. -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. - -Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. +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. ## 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. - 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 -an internal list of Certificate Authorities, -which means the certificate cannot be self-signed. +an internal list of Certificate Authorities, which means the certificate cannot +be self-signed. You can turn this off in the webhook settings in your GitLab projects. ![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. @@ -121,7 +131,7 @@ X-Gitlab-Event: Push Hook } ``` -## Tag events +### Tag events 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. @@ -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. The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The @@ -253,7 +263,7 @@ Valid target types: 3. `issue` 4. `snippet` -### Comment on commit +#### Comment on commit **Request header**: @@ -332,7 +342,7 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on merge request +#### Comment on merge request **Request header**: @@ -459,7 +469,7 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on issue +#### Comment on issue **Request header**: @@ -534,7 +544,7 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on code snippet +#### Comment on code snippet **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. @@ -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. @@ -737,9 +747,9 @@ X-Gitlab-Event: Wiki Page Hook }, "wiki": { "web_url": "http://example.com/root/awesome-project/wikis/home", - "git_ssh_url": "git@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", + "git_ssh_url": "git@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", "default_branch": "master" }, "object_attributes": { @@ -754,7 +764,7 @@ X-Gitlab-Event: Wiki Page Hook } ``` -## Pipeline events +### Pipeline events 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. @@ -935,7 +944,7 @@ X-Gitlab-Event: Build Hook **Request Body**: -``` +```json { "object_kind": "build", "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 -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 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 `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",} -- cgit v1.2.3