178 lines
4.5 KiB
Markdown
178 lines
4.5 KiB
Markdown
# Webhookey
|
|
Webhookey is a web server listening for requests as for example sent by
|
|
gitea's webhooks. Further, Webhookey allows you to specify rules
|
|
which are matched against the data received to trigger certain
|
|
actions.
|
|
|
|
## Build
|
|
|
|
### Install Rust
|
|
Install the Rust toolchain from [rustup.rs](https://rustup.rs).
|
|
|
|
### Build Webhookey
|
|
The Webhookey project can be built for development:
|
|
``` sh
|
|
cargo b
|
|
```
|
|
|
|
or for releasing:
|
|
``` sh
|
|
cargo b --release
|
|
```
|
|
|
|
### Install Webhookey
|
|
When a Rust toolchain installed you can also install Webhookey
|
|
directly without cloning it manually:
|
|
``` sh
|
|
cargo install --git https://git.onders.org/finga/webhookey.git webhookey
|
|
```
|
|
|
|
or from within the project:
|
|
``` sh
|
|
cargo install webhookey
|
|
```
|
|
|
|
### Run Webhookey
|
|
Webhookey can either be run from the project directory with:
|
|
``` sh
|
|
cargo b
|
|
```
|
|
|
|
or you can copy the produced binary somewhere else from
|
|
`webhookey/target/{debug,release}/webhookey` depending on which one
|
|
you built.
|
|
|
|
## Configuration
|
|
Configuration syntax is YAML and it's paths as well as it's
|
|
configuration format is described in the following sections.
|
|
|
|
### Configuration Paths
|
|
Following locations are checked for a configuration file:
|
|
- `/etc/webhookey/config.yml`
|
|
- `<config_dir>/webhookey/config.yml`
|
|
- `./config.yml`
|
|
|
|
Whereas `<config_dir>` depends on the platform:
|
|
- Linux: `$XDG_CONFIG_HOME` or `$HOME/.config`
|
|
- macOS: `$HOME/Library/Application Support`
|
|
- Windows: `{FOLDERID_RoamingAppData}`
|
|
|
|
### Configuration parameters
|
|
|
|
#### Metrics
|
|
A metrics page can optionally enabled to query stats of the currently
|
|
running webhookey instance. Note that stats are lost between restarts
|
|
of webhookey as those are not stored persistently.
|
|
|
|
Example:
|
|
```yaml
|
|
metrics:
|
|
enabled: true
|
|
ip_filter:
|
|
allow:
|
|
- 127.0.0.1/31
|
|
```
|
|
|
|
#### Hooks
|
|
With `hooks` you can configure a sequence of hooks. A single hook
|
|
consists of the following fields:
|
|
- `command`: A command to be executed if a filter matches
|
|
- `allow`/`deny`: An optional parameter to either allow or deny
|
|
specific source addresses or ranges.
|
|
- `signature`: Name of the HTTP header field containing the signature.
|
|
- `secrets`: List of secrets.
|
|
- `filter`: Tree of filters.
|
|
|
|
Example:
|
|
```yaml
|
|
hooks:
|
|
hook1:
|
|
command: /usr/bin/local/script_xy.sh {{ /repository/name }}
|
|
signature: X-Gitea-Signature
|
|
ip_filter:
|
|
allow:
|
|
- 127.0.0.1
|
|
- 127.0.0.1/31
|
|
secrets:
|
|
- secret_key_01
|
|
- secret_key_02
|
|
filter:
|
|
or:
|
|
- json:
|
|
pointer: /ref
|
|
regex: refs/heads/master
|
|
- and:
|
|
- json:
|
|
pointer: /ref
|
|
regex: refs/heads/a_branch
|
|
- json:
|
|
pointer: /after
|
|
regex: f6e5fe4fe37df76629112d55cc210718b6a55e7e
|
|
```
|
|
|
|
##### Command
|
|
To pass data to a command following two different methods can be used.
|
|
|
|
Example: `script_foo {{ header X-Gitea-Event }} {{ /field/foo }}`
|
|
|
|
###### JSON Pointers
|
|
Use JSON pointers ([RFC 6901](https://tools.ietf.org/html/rfc6901))
|
|
point to values of a JSON field from the JSON data.
|
|
|
|
Example: `{{ /field/pointed/to }}`.
|
|
|
|
###### Header
|
|
Use values from header fields sent with the HTTP request.
|
|
|
|
Example: `{{ header X-Gitea-Event }}`.
|
|
|
|
##### Allow and Deny
|
|
To allow or deny specific network ranges source is an optional
|
|
configuration parameter which either contains an allow or a deny field
|
|
with sequences containing networks. Note that IPv6 addresses have to
|
|
be put in single quotes due to the colons.
|
|
|
|
Example:
|
|
```yaml
|
|
allow:
|
|
- 127.0.0.1
|
|
- 127.0.0.1/31
|
|
- "::1"
|
|
```
|
|
|
|
```yaml
|
|
deny:
|
|
- 127.0.0.1
|
|
- 127.0.0.1/31
|
|
- "::1"
|
|
```
|
|
|
|
##### Signature
|
|
Set the name of the HTTP header field containing the HMAC signature.
|
|
|
|
##### Secrets
|
|
Configure a list of secrets to validate the hook.
|
|
|
|
##### Filter
|
|
Filter can be either a concrete filter or a conjunction
|
|
filter. Concrete filters return either true or false on specific
|
|
constraints. Conjunction filters contain lists of filters which are
|
|
evaluated and combined based on the type. The result is either used
|
|
for parent conjunction filters or, if at the root, used to decide if a
|
|
hook should be executed.
|
|
|
|
###### Conjunction Filters
|
|
Conjunction filters contain lists of other filters.
|
|
- `and`: Logical conjunction.
|
|
- `or`: Logical disjunction.
|
|
|
|
###### Concrete Filters
|
|
- `json`:
|
|
|
|
The `json` filter matches a regular expression on a field from the
|
|
received JSON data.
|
|
|
|
- `pointer`: Pointer to the JSON field according to [RFC
|
|
6901](https://tools.ietf.org/html/rfc6901).
|
|
- `regex`: Regular expression which has to match the field pointed
|
|
to by the pointer.
|