Pirate is a webhooks task runner. It aims to satisfy the need for running tasks based on webhook events.
Command line flag
You can pass in a config file using the -config
flag:
pirate -config ./path/to/ship.yml
Environment variable
You can set the environment variable: PIRATE_CONFIG_PATH
Default location
If running without a config flag, it will look for a ship.yml
in the current directory.
Example config (see ship.sample.yml).
server:
# optional: defaults to 'localhost'
host: localhost
# required: port on which to listen to
port: 3939
# optional: maximum time allowed for a request, defaults to 5m0s
request-timeout: '2m30s'
# optional: maximum size of the header bytes, defaults to 1k
max-header-bytes: '10M'
logging:
# required: logging directory.
# Will be created with permission 744 if it doesn't exist
# Filename will be pirate.YYYY-MM-DD--hh:mm:ss.log
dir: './logs'
## NOTE: special value :stdout: writes to standard output
# dir: ':stdout:'
handlers:
# NOTE: all fields of the handler are required unless stated otherwise
- endpoint: /webhooks/simple
name: simple webhook handler
# optional: handler execution policy, one of: drop, queue, parallel. Defaults to queue.
policy: drop
# authenticates the handler based on the value of the X-Authorization header
auth:
# a list validator will check if the token matches one of .token
validator: list
token:
- alpha
- beta
# script to run, the request headers and body are available as env vars.
run: |
SOME_VAR="some-variable"
echo "SOME_VAR: $SOME_VAR"
echo "body: $PIRATE_BODY"
echo "headers: $PIRATE_HEADERS"
echo "header param: $PIRATE_HEADERS_SOME_PARAM"
- endpoint: /new-release
name: new release
policy: queue
auth:
# a command validator will pass if the run block exits with code = 0.
validator: command
run: |
echo "offloading validation to another program"
./path/to/validator --token="$PIRATE_TOKEN" --name="$PIRATE_NAME"
run: |
# one can call scripts from the run block, this which makes it easier
# to implement complex workflows
./scripts/handle-new-release.sh "$PIRATE_BODY"
We provide pre-built binaries for Linux on the releases page.
See Releases.
You can also just run the following command:
curl -L -s -O https://github.com/aalbacetef/pirate/releases/download/v0.1.1/pirate && chmod +x ./pirate
We provide a docker image for ease of use.
The recommended way of using it is to mount your ship config as well as any needed directories.
Example:
docker run --rm -it \
-v ./logs/:/app/logs \
-v ./ship.yml:/app/ship.yml \
-v /var/www/html:/app/blog-html \
-p 39390:39390 \
aalbacetef/pirate:latest
Tips
Don’t forget to set server.host
to 0.0.0.0
.
Some users might find it useful to set the logging to standard output, while others would prefer to mount the log directory.
Pirate uses a YAML configuration file (ship.yml
) to define server settings, logging, and webhook handlers.
The server
section defines how Pirate listens for incoming webhook requests.
server:
host: localhost # Optional: Defaults to 'localhost'
port: 3939 # Required: The port Pirate listens on
request-timeout: '5m0s' # Optional: Defaults to 5 minutes
max-header-bytes: '1k' # Optional: Maximum size of request headers. Defaults to 1k (1024 bytes)
-
host
(optional) - The address Pirate binds to. Defaults tolocalhost
. -
port
(required) - The port number Pirate listens on. -
request-timeout
(optional) - Maximum duration for processing a request. Defaults to5m0s
. -
max-header-bytes
(optional) - Maximum size of request headers. Accepts values like5k
,10M
,1G
, or plain numbers (e.g.,2048
). Defaults to1k
(1024 bytes).
The logging
section controls where logs are stored.
logging:
dir: './logs' # Required: Log directory or `:stdout:` for console output
-
dir
(required) - Directory where logs are saved.-
If the directory does not exist, Pirate creates it with 744 permissions.
-
Log files follow the format:
pirate.YYYY-MM-DD—HH:mm:ss.log
. -
Special value
:stdout:
writes logs to standard output.
-
The handlers
section defines webhook endpoints, authentication, and execution scripts.
handlers:
- endpoint: /webhooks/simple
name: simple webhook handler
policy: drop
auth:
validator: list
token:
- alpha
- beta
run: |
echo "body: $PIRATE_BODY"
echo "headers: $PIRATE_HEADERS"
Each handler includes:
-
endpoint
(required) - The URL path for this webhook (e.g.,/webhooks/simple
). -
name
(required) - A human-readable name for the handler. -
policy
(optional) - Execution policy. One ofdrop
,parallel
,queue
. Defaults toqueue
.-
drop
: if webhook events come in while the handler is already running, they will be dropped. -
parallel
: handlers will run as webhooks come in. -
queue
: handlers will be queued as they come in.
-
-
auth
(required, one oflist
orcommand
) - Authentication method:-
validator: list
- Checks if theX-Authorization
header matches one of the provided tokens. -
validator: command
- Runs a script and passes authentication if it exits with0
.
-
-
run
(required) - A shell script executed when the webhook is triggered. Available environment variables:-
$PIRATE_BODY
: The request body. -
$PIRATE_HEADERS
: All request headers. -
$PIRATE_HEADERS_<HEADER_NAME>
: A specific header value.
-
auth:
validator: list
token:
- alpha
- beta
Passes if X-Authorization
header matches one of the values of the token
list, in this case: alpha
or beta
.
auth:
validator: command
run: |
echo "running validation via a script"
./scripts/validate-user.sh "$PIRATE_TOKEN"
Passes if the run block exits with exit code 0.
The X-Authorization
header’s value is exposed as an environment variable: PIRATE_TOKEN
.
The handler name is exposed as an environment variable: PIRATE_NAME
.
-
We assume users are running pirate behind some reverse-proxy like NGINX so not much care has been given to reimplement features offered by it (for the MVP), like rate-limiting, but will be added in the future.
-
Don’t use easy tokens for auth. If you need stricter checks use the command validator for more complex auth logic. In the future this will probably be passed a lot more request metadata.
-
Pirate creates its scripts by default under /tmp (which it cleans up after running). In the future this will be configurable.
-
Pirate responds with 404 even if validation fails, to not leak information. It does return a 405 if any method other than POST is used, but this shouldn’t leak more information than only POST is accepted.
This tool assumes you trust yourself. If you’re exposing it to the internet, make sure you know what you’re doing. You’re the captain here, pirate doesn’t stop you from walking the plank if you tell it to.