Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/aalbacetef/pirate

A webhooks taskrunner - run tasks easily based on webhooks!
https://github.com/aalbacetef/pirate

go golang taskrunner webhook webhooks

Last synced: 5 months ago
JSON representation

A webhooks taskrunner - run tasks easily based on webhooks!

Awesome Lists containing this project

README 

          
= pirate 

:author: Arturo Albacete

:revdate: 2025-04-10

:toc: macro

:toclevels: 5



image:https://github.com/aalbacetef/pirate/actions/workflows/ci.yml/badge.svg[CI status] 

image:https://img.shields.io/badge/License-BSD_3--Clause-blue.svg[License] 

image:https://goreportcard.com/badge/github.com/aalbacetef/pirate[Go Report Card]



toc::[]



== Introduction 



image::misc/pirate-ship.jpg[] 



**Pirate** is a webhooks task runner. It aims to satisfy the need for running tasks based on webhook events.



=== Running it



**Command line flag**



You can pass in a config file using the `-config` flag:



[source,bash]

----

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 link:ship.sample.yml[ship.sample.yml]).

[source,yaml]

----

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"

----



== Installation



=== Binaries



We provide pre-built binaries for Linux on the releases page.



See link:https://github.com/aalbacetef/pirate/releases[Releases].



You can also just run the following command:

[source,bash]

----

curl -L -s -O https://github.com/aalbacetef/pirate/releases/download/v0.1.1/pirate && chmod +x ./pirate

----



=== Docker 



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:



[source,bash]

----

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.



== Configuration



Pirate uses a YAML configuration file (`ship.yml`) to define server settings, logging, and webhook handlers.



=== Server Configuration



The `server` section defines how Pirate listens for incoming webhook requests.



[source,yaml]

----

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 to `localhost`.

- *`port`* (required) - The port number Pirate listens on.

- *`request-timeout`* (optional) - Maximum duration for processing a request. Defaults to `5m0s`.

- *`max-header-bytes`* (optional) - Maximum size of request headers. Accepts values like `5k`, `10M`, `1G`, or plain numbers (e.g., `2048`). Defaults to `1k` (1024 bytes).



=== Logging Configuration



The `logging` section controls where logs are stored.



[source,yaml]

----

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.



=== Webhook Handlers



The `handlers` section defines webhook endpoints, authentication, and execution scripts.



==== Example Handler



[source,yaml]

----

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 of `drop`, `parallel`, `queue`. Defaults to `queue`. 

** `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 of `list` or `command`) - Authentication method:

** *`validator: list`* - Checks if the `X-Authorization` header matches one of the provided tokens.

** *`validator: command`* - Runs a script and passes authentication if it exits with `0`.

* *`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_`: A specific header value.



==== Authentication Methods



===== Token-based Authentication



[source,yaml]

----

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`.



===== Command-based Authentication



[source,yaml]

----

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`.



=== Running External Scripts



Pirate allows running external scripts to handle complex workflows.



[source,yaml]

----

run: |

  ./scripts/handle-new-release.sh

----



== Notes On Security



- 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.