diff options
Diffstat (limited to 'doc/web_hooks/web_hooks.md')
| -rw-r--r-- | doc/web_hooks/web_hooks.md | 133 |
1 files changed, 101 insertions, 32 deletions
diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md index 33c1a79d59c..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.  -## 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,12 +932,70 @@ X-Gitlab-Event: Pipeline Hook } ``` -#### Example webhook receiver +### Build events + +Triggered on status change of a Build. + +**Request Header**: + +``` +X-Gitlab-Event: Build Hook +``` + +**Request Body**: + +```json +{ + "object_kind": "build", + "ref": "gitlab-script-trigger", + "tag": false, + "before_sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", + "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", + "build_id": 1977, + "build_name": "test", + "build_stage": "test", + "build_status": "created", + "build_started_at": null, + "build_finished_at": null, + "build_duration": null, + "build_allow_failure": false, + "project_id": 380, + "project_name": "gitlab-org/gitlab-test", + "user": { + "id": 3, + "name": "User", + "email": "user@gitlab.com" + }, + "commit": { + "id": 2366, + "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", + "message": "test\n", + "author_name": "User", + "author_email": "user@gitlab.com", + "status": "created", + "duration": null, + "started_at": null, + "finished_at": null + }, + "repository": { + "name": "gitlab_test", + "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", + "description": "Atque in sunt eos similique dolores voluptatem.", + "homepage": "http://192.168.64.1:3005/gitlab-org/gitlab-test", + "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", + "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", + "visibility_level": 20 + } +} +``` + +## 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' @@ -947,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",<SNIP>} |