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: 3 months ago
JSON representation

A webhooks taskrunner - run tasks easily based on webhooks!

• Host: GitHub
• URL: https://github.com/aalbacetef/pirate
• Owner: aalbacetef
• License: bsd-3-clause
• Created: 2024-10-19T18:42:13.000Z (8 months ago)
• Default Branch: master
• Last Pushed: 2025-03-19T16:41:18.000Z (3 months ago)
• Last Synced: 2025-03-19T17:32:06.882Z (3 months ago)
• Topics: go, golang, taskrunner, webhook, webhooks
• Language: Go
• Homepage:
• Size: 65.4 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.asciidoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= pirate 

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]

Note: this is a WIP.

:toc: 

== Introduction 

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

Example config (explained below).

[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 5m 

  request-timeout: '5m0s'

  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:

  # all fields of the handler are required

  - endpoint: /webhooks/simple

    name: simple webhook handler

    # 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

    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

TBC

== 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: '5m' # Optional: Defaults to 5 minutes

----

- *`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 (default: `5m`).

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

    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.

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

----