NAME

snare — GitHub webhooks runner

SYNOPSIS

snare [-c config-file] [-d] [-v]

DESCRIPTION

snare is a GitHub webhooks daemon. When snare receives a webhook event from a given repository, it authenticates the request, and then executes a user-defined “per-repo program” with information about the webhook event. The “per-repo program” is run in a freshly created temporary directory which is removed once it has completed.

The options are as follows:

-c config-file: is a path to a snare.conf configuration file. If not specified, snare assumes the configuration file is located at /etc/snare/snare.conf/.
-d: tells snare not to daemonise: in other words, `snare` stays in the foreground and logs errors to stderr. This can be useful for debugging.
-v: enables more verbose logging. -v may be specified multiple times, with each increasing the quantity of logging.

INTEGRATION WITH GITHUB

snare runs an HTTP server which GitHub can send webhook requests to. Configuring a webhook for a given GitHub repository is relatively simple: go to that repository, then “Settings > Webhooks > Add webhook”. For “payload”, specify “http://yourmachine.com:port/”, specify a “secret” (which you will then reuse as the secret in snare.conf(5)) and then choose which events you wish GitHub to deliver.

HTTPS/TLS

snare runs an HTTP server. If you wish, as is recommended, to send your webhooks over an encrypted connection, you will need to run a proxy in front of snare.

DIAGNOSTICS

When run as a daemon, snare logs to syslogd(8) under the “daemon” facility.