From 9e5ebb599a9b4a9eec9443a1a1814695098c1611 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Hajdarevi=C4=87?= Date: Tue, 13 Jan 2015 03:20:58 +0100 Subject: [PATCH 1/3] Update README.md --- README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/README.md b/README.md index e69de29..ef16f3e 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,127 @@ +# Installing + ```go + go get github.com/adnanh/webhook + ``` + +# Updating + ```go + go get -u github.com/adnanh/webhook + ``` + +# Adding hooks + Hooks are defined using JSON format. The hooks file must contain an array of JSON formatted hooks. Here is an example of a valid hooks file containing one hook. The hook will be triggered whenever a push to the master branch occurrs. + ```json + [ + { + "id": "hook-1", + "command": "OS command to be executed when the hook gets triggered", + "cwd": "current working directory under which the specified command will be executed (optional, defaults to the directory where the binary resides)", + "secret": "secret key used to compute the hash of the payload (optional)", + "trigger-rule": + { + "match": + { + "parameter": "ref", + "value": "refs/heads/master" + } + } + } + ] + ``` +# Trigger rules +### And +*And rule* will evaluate to _true_, if and only if all of the sub rules evaluate to _true_. +```json +{ +"and": + [ + { + "match": + { + "parameter": "ref", + "value": "refs/heads/master" + } + }, + { + "match": + { + "parameter": "repository.owner.name", + "value": "adnanh" + } + } + ] +} +``` +### Or +*Or rule* will evaluate to _true_, if any of the sub rules evaluate to _true_. +```json +{ +"or": + [ + { + "match": + { + "parameter": "ref", + "value": "refs/heads/master" + } + }, + { + "match": + { + "parameter": "ref", + "value": "refs/heads/development" + } + } + ] +} +``` +### Not +*Not rule* will evaluate to _true_, if and only if the sub rule evaluate to _false_. +```json +{ +"not": + { + "match": + { + "parameter": "ref", + "value": "refs/heads/master" + } + } +} +``` +### Match +*Match rule* will evaluate to _true_, if and only if the payload structure contains the key specified in the `parameter` value, contains same value as specified in the `value` value. +*Please note:* due to technical limitations, _number_ and _boolean_ values in hooks file must be wrapped around with quotes. + +```json +{ + "match": + { + "parameter": "ref", + "value": "refs/heads/master" + } +} +``` + +It is possible to specify the values deeper in the payload JSON object with the dot operator, and if a value of the specified key is an array, it's possible to index the array values by using the number instead of string as the key, as shown in a following example: +```json +{ + "match": + { + "parameter": "commits.0.author.username", + "value": "adnanh" + } +} +``` +# Running +In your `$GOPATH/bin` directory, you should have `webhook` binary. + +Simply running the binary using `./webhook` command, will start the webhook with the default options. That means the webhook will listen on all interfaces on port 9000. It will try to read and parse `hooks.json` file from the same directory where the binary is located, and it will log everything to stdout and the file `webhook.log`. + +To override any of these options, you can use the following command line flags: +```bash +-hooks="hooks.json": path to the json file containing defined hooks the webhook should serve +-ip="": ip the webhook server should listen on +-log="webhook.log": path to the log file +-port=9000: port the webhook server should listen on +``` From 624d94e736bc8fd85eb80376ae7954fd94121bc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Hajdarevi=C4=87?= Date: Tue, 13 Jan 2015 03:37:18 +0100 Subject: [PATCH 2/3] Update README.md refactoring --- README.md | 77 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index ef16f3e..27f12b7 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,39 @@ -# Installing - ```go - go get github.com/adnanh/webhook - ``` +# webhook -# Updating - ```go - go get -u github.com/adnanh/webhook - ``` +## Installing +*Please note:* Before installing the webhook, make sure you have installed `go` and properly set up your `$GOPATH` environment variable. + +```go +go get github.com/adnanh/webhook +``` + +## Updating +```go +go get -u github.com/adnanh/webhook +``` -# Adding hooks - Hooks are defined using JSON format. The hooks file must contain an array of JSON formatted hooks. Here is an example of a valid hooks file containing one hook. The hook will be triggered whenever a push to the master branch occurrs. - ```json - [ +## Adding hooks +Hooks are defined using JSON format. The _hooks file_ must contain an array of JSON formatted hooks. Here is an example of a valid _hooks file_ containing only one hook. The hook will be triggered whenever a push to the master branch occurrs. + +```json +[ + { + "id": "hook-1", + "command": "OS command to be executed when the hook gets triggered", + "cwd": "current working directory under which the specified command will be executed (optional, defaults to the directory where the binary resides)", + "secret": "secret key used to compute the hash of the payload (optional)", + "trigger-rule": { - "id": "hook-1", - "command": "OS command to be executed when the hook gets triggered", - "cwd": "current working directory under which the specified command will be executed (optional, defaults to the directory where the binary resides)", - "secret": "secret key used to compute the hash of the payload (optional)", - "trigger-rule": + "match": { - "match": - { - "parameter": "ref", - "value": "refs/heads/master" - } + "parameter": "ref", + "value": "refs/heads/master" } } - ] - ``` -# Trigger rules + } +] +``` +## Trigger rules ### And *And rule* will evaluate to _true_, if and only if all of the sub rules evaluate to _true_. ```json @@ -90,20 +95,21 @@ } ``` ### Match -*Match rule* will evaluate to _true_, if and only if the payload structure contains the key specified in the `parameter` value, contains same value as specified in the `value` value. -*Please note:* due to technical limitations, _number_ and _boolean_ values in hooks file must be wrapped around with quotes. +*Match rule* will evaluate to _true_, if and only if the payload JSON object contains the key specified in the `parameter` field that has the same value as specified in the `value` field. + +*Please note:* Due to technical reasons, _number_ and _boolean_ values in the _hooks file_ must be wrapped around with a pair of quotes. ```json { "match": { - "parameter": "ref", - "value": "refs/heads/master" + "parameter": "repository.id", + "value": "123456" } } ``` -It is possible to specify the values deeper in the payload JSON object with the dot operator, and if a value of the specified key is an array, it's possible to index the array values by using the number instead of string as the key, as shown in a following example: +It is possible to specify the values deeper in the payload JSON object with the dot operator, and if a value of the specified key happens to be an array, it's possible to index the array values by using the number instead of a string as the key, which is shown in the following example: ```json { "match": @@ -113,10 +119,11 @@ It is possible to specify the values deeper in the payload JSON object with the } } ``` -# Running -In your `$GOPATH/bin` directory, you should have `webhook` binary. +## Running +After installing webhook, in your `$GOPATH/bin` directory you should have `webhook` binary. -Simply running the binary using `./webhook` command, will start the webhook with the default options. That means the webhook will listen on all interfaces on port 9000. It will try to read and parse `hooks.json` file from the same directory where the binary is located, and it will log everything to stdout and the file `webhook.log`. +By simply running the binary using the `./webhook` command, the webhook will start with the default options. +That means the webhook will listen on _all interfaces_ on port `9000`. It will try to read and parse `hooks.json` file from the same directory where the binary is located, and it will log everything to `stdout` and the file `webhook.log`. To override any of these options, you can use the following command line flags: ```bash @@ -125,3 +132,7 @@ To override any of these options, you can use the following command line flags: -log="webhook.log": path to the log file -port=9000: port the webhook server should listen on ``` + +All hooks are served under the `http://ip:port/hook/:id`, where the `:id` corresponds to the hook *id* specified in _hooks file_. + +Visiting `http://ip:port` will show version, uptime and number of hooks the webhook is serving. From dcc5b846b25054269c29b6e90d425ac4e2ff9650 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Hajdarevi=C4=87?= Date: Tue, 13 Jan 2015 03:37:47 +0100 Subject: [PATCH 3/3] Update README.md refactoring --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 27f12b7..7923e5c 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ *Please note:* Before installing the webhook, make sure you have installed `go` and properly set up your `$GOPATH` environment variable. ```go -go get github.com/adnanh/webhook +$ go get github.com/adnanh/webhook ``` ## Updating ```go -go get -u github.com/adnanh/webhook +$ go get -u github.com/adnanh/webhook ``` ## Adding hooks