A validating proxy to facilitate secure delivery of GitHub webhook payloads to multiple targets behind a firewall.
- Support for multiple backend webhook targets
- GitHub payload validation based on HMAC-SHA256
- Optional secret storage in HashiCorp Vault K/V store
By default, the daemon will look for a Viper-style configuration file with the prefix "config" (i.e. config.yaml
for YAML configuration, config.toml
if you prefer TOML, etc.) in /etc/github-hook-proxy
followed by the current working directory.
The following root configuration keys are supported:
listener
: (optional) listener configuration (default:{address: 127.0.0.1, port: 8080, tls: {}}
)targets
: (required) list of targets (default:[]
)vault
: (optional) vault configuration (default:{}
)verbose
: (optional) if set, debug mode will be enabled (default:false
)
address
: (optional) listener bind address (default:127.0.0.1
)port
: (optional) listener bind port (default:8080
)tls
: (optional) listener TLS certificate configuration, see below (default:{}
)
The tls
key if specified should contain two keys which, when set, will cause the proxy to listen for HTTPS rather than HTTP requests:
private-key
: (required) path to PEM format TLS private keypublic-key
: (required) path to PEM format TLS public key
Each target object takes the form "<targetName>": {}
, with the following keys supported:
url
: (required) full URL to which payloads for this target should be forwardedsecret
: (optional) shared secret for validation of payloads associated with this target (default: load from vault); an explicitly blank secret (secret: ""
) will disable payload validationevents
: (optional) list of events to accept for this target (default:[ping, push, pull_request]
)jenkins-validation
: (optional) boolean controlling whether to accept Jenkins GitHub plugin validation requests (default:false
); not required for Jenkins to receive externally configured webhook payloads
If any target does not specify a static secret, then Vault must be configured:
address
: (optional) full URL of your Vault instance (default:https://127.0.0.1:8080
); may also be specified via VAULT_ADDR.token-file
: (optional) path to Vault token file; the VAULT_TOKEN environment variable will take priority.mount
: (optional) mountpoint of the Vault K/V v2 store holding target webhook secrets (default:secret
)secret
: (optional) template string for the path within the Vault K/V v2 store holding a specific target's webhook secret; must contain a single%s
which will be filled in with each target's name. (default:github-webhooks/%s
)field
: (optional) field within the target's K/V v2 secret holding the GitHub webhook secret (default:secret
)
See example-config.yaml
for example configuration.