Githook
Sign Up

Documentation

Drivers

Configure delivery drivers in OSS.

Githook uses Watermill for publishing and subscribing. Driver configuration lives under watermill in config.yaml. This page mirrors docs/drivers.md.

Publisher vs worker

  • Publisher (server): use driver or drivers for fan-out
  • Subscriber (worker): use driver or drivers for fan-in

Publisher (fan-out)

watermill:
  drivers: [amqp, http]
  amqp:
    url: amqp://guest:guest@localhost:5672/
    mode: durable_queue
  http:
    mode: base_url
    base_url: http://some-other-service/hooks

Worker (fan-in)

watermill:
  drivers: [amqp, nats, kafka]

watermill:
  driver: amqp
  amqp:
    url: amqp://guest:guest@localhost:5672/

Driver reference

GoChannel

In-memory pub/sub, ideal for local development and testing. This is the default driver if none is specified.

  • persistent: If true, the channel is not closed when all subscribers are gone.
  • output_buffer: The size of the output channel buffer.
watermill:
  driver: gochannel
  gochannel:
    output_buffer: 64
    persistent: false
    block_publish_until_subscriber_ack: false

Kafka

  • brokers: A list of Kafka broker addresses.
  • consumer_group: (Worker-only) The consumer group for the worker.
watermill:
  driver: kafka
  kafka:
    brokers: ["kafka-broker-1:9092", "kafka-broker-2:9092"]
    consumer_group: "my-githook-worker-group"

NATS Streaming

  • cluster_id: The NATS Streaming cluster ID.
  • client_id: A unique client ID for the connection.
  • client_id_suffix: (Worker-only) An optional suffix to ensure uniqueness across worker replicas.
  • url: The address of the NATS server.
watermill:
  driver: nats
  nats:
    cluster_id: test-cluster
    client_id: githook-publisher
    client_id_suffix: "-worker-1"
    url: nats://localhost:4222

AMQP (RabbitMQ)

  • url: The AMQP connection string.
  • mode: durable_queue, nondurable_queue, durable_pubsub, or nondurable_pubsub.
watermill:
  driver: amqp
  amqp:
    url: amqp://guest:guest@rabbitmq:5672/
    mode: durable_queue

SQL (Postgres/MySQL)

  • driver: The Go database driver name (postgres or mysql).
  • dsn: The database connection string.
  • dialect: The SQL dialect (postgres or mysql).
  • auto_initialize_schema: If true, Githook creates the required table if missing.

Note: your application must blank-import the required database driver (for example, _ "github.com/lib/pq").

watermill:
  driver: sql
  sql:
    driver: postgres
    dsn: postgres://user:pass@localhost:5432/dbname?sslmode=disable
    dialect: postgres
    auto_initialize_schema: true

RiverQueue (Postgres)

Publishes events as jobs to a River queue. The Go SDK can also consume RiverQueue jobs using the same driver config via the Drivers API.

  • driver: The Go database driver for River (postgres).
  • dsn: The database connection string.
  • table: The River jobs table name (default: river_job). For workers, only river_job or schema.river_job is supported.
  • queue: The queue to insert jobs into (default: default).
  • kind: The job kind to insert. This should match a registered River worker.
  • tags: Optional tags for the job.
  • max_workers: (Workers only) Max workers for the queue (default: 5).
watermill:
  driver: riverqueue
  riverqueue:
    driver: postgres
    dsn: postgres://user:pass@localhost:5432/dbname?sslmode=disable
    table: river_job
    queue: high_priority
    kind: githook.event
    max_attempts: 25
    priority: 1
    tags: ["githook", "webhook"]

HTTP (publish-only)

Publishes events via HTTP POST. This driver cannot be used by workers.

  • mode:
    • topic_url: the topic name is treated as the full URL to POST to.
    • base_url: the topic name is appended to the base_url.
  • base_url: The base URL for the webhook endpoint.
watermill:
  driver: http
  http:
    mode: base_url
    base_url: http://another-service:8080/webhooks

Publish failure handling

Configure retry and optional DLQ routing:

watermill:
  publish_retry:
    attempts: 3
    delay_ms: 500
  dlq_driver: amqp