Skip to content
coderPublic

About

GitHub webhook events for AI agents over MCP: a Go library with a thin server

Resources

Code of conduct

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

faucet

GitHub events for AI agents, over MCP.

GitHub sends webhooks to faucet, which stores them in Postgres. Agents read the events over MCP by waiting, polling or subscribing, and a scheduler calls the cron routes that deliver, redeliver and purge.

An agent that opened a PR usually has to keep polling GitHub to find out whether CI passed or a reviewer answered. With faucet, it asks once and waits. Faucet receives GitHub webhooks, stores them as typed events in Postgres, and hands them to agents over MCP.

Faucet is a Go library first, with a thin HTTP server on top, so coder/coder can embed it in coderd.

What an agent gets

Three ways to consume events: wait with one tool call that returns on the first match, poll with a cursor, or subscribe and receive signed webhooks.
  • Wait. The wait_for_github_events tool long-polls (up to 50 seconds) and returns as soon as a matching event exists. Pass back the returned cursor to continue with no gaps or repeats.
  • Poll. events/list and events/poll from the draft MCP Events extension (SEP-3415).
  • Subscribe. events/subscribe registers a callback URL. Faucet sends each matching event to it as a signed Standard Webhooks request. See docs/webhooks.md.

An agent asks for events of one repo by name, optionally narrowed by sha, pr, GitHub's actions and field filters such as head_branch or conclusion. A name is a family or one of its exact types (see docs/events.md):

Family GitHub event Exact types
ci.runs workflow_run ci.run_completed
ci.jobs workflow_job none
ci.checks check_run ci.check_completed
ci.suites check_suite none
ci.statuses status none
pr.activity pull_request pr.closed
pr.reviews pull_request_review pr.review_submitted
pr.comments issue_comment pr.comment_created
pr.review_comments pull_request_review_comment none
pr.review_threads pull_request_review_thread none

Every /github/mcp request carries Authorization: Bearer <GitHub token>. Faucet reads with the caller's token: it only returns events for repositories that the token can read. The one GitHub token it holds, for redelivery, is optional. See docs/security.md. A service agent can log in with a client ID and secret instead, with no GitHub token (see docs/service-accounts.md).

Faucet also deletes events after a retention period, and it can ask GitHub to redeliver webhooks that failed while it was down.

Quick start

You need Go and Postgres 13 or newer.

DATABASE_URL='postgres://postgres@127.0.0.1:5432/postgres?sslmode=disable' \
GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)" \
go run ./cmd/faucet

The server listens on PORT (default 8080) and applies migrations at startup. Then add a webhook to your GitHub org or repository:

  • Payload URL: https://<your host>/webhook/github
  • Content type: application/json
  • Secret: the value of GITHUB_WEBHOOK_SECRET
  • Events: "Let me select individual events", then Pull requests, Pull request reviews, Pull request review comments, Pull request review threads, Issue comments, Workflow runs, Workflow jobs, Check runs, Check suites and Statuses (see docs/events.md)

Point any MCP client at https://<your host>/github/mcp with a GitHub token as the bearer token. /mcp serves the same endpoint as an alias for one release (see docs/upgrading.md).

Configuration

Variable Required Purpose
DATABASE_URL yes Postgres connection for requests. A transaction-mode pooler works.
DATABASE_URL_UNPOOLED no Direct connection for migrations, when DATABASE_URL is a pooler.
GITHUB_WEBHOOK_SECRET yes The GitHub webhook's secret, at least 16 bytes.
PORT no Listen port. Default 8080.
FAUCET_GITHUB_API_URL no GitHub API base URL. Default https://api.github.com.
CRON_SECRET for cron routes Bearer token for /cron/*: 16 to 1024 printable ASCII characters, no spaces. Unset turns the cron routes off.
FAUCET_RETENTION_DAYS no How many days events are kept, from 1 to 3650. Default 30.
FAUCET_WEBHOOK_KEY for webhooks 32 random bytes, base64. Seals subscriber secrets at rest.
FAUCET_WEBHOOK_CALLBACK_VERIFICATION no How webhook mode checks callback URLs: allowlist (default) or handshake.
FAUCET_WEBHOOK_ALLOWED_ORIGINS in allowlist mode Comma-separated https://host[:port] origins that may receive webhooks. Must be unset in handshake mode.
FAUCET_HOOK_TOKEN for redelivery GitHub token that lists and redelivers the hook's deliveries.
FAUCET_HOOK_ID for redelivery Numeric ID of the GitHub webhook to watch for failed deliveries.
FAUCET_HOOK_ORG for an org hook The organization that owns the hook. Set this or FAUCET_HOOK_REPO, not both.
FAUCET_HOOK_REPO for a repo hook The repository that owns the hook, as owner/name.
FAUCET_PUBLIC_URL for service accounts Faucet's public URL, such as https://faucet.example.com, with no path or trailing slash. Turns on faucet's login server for service clients (see docs/service-accounts.md).
VERCEL set by Vercel Marks a Vercel deployment. There the server never migrates without VERCEL_ENV.
VERCEL_ENV set by Vercel When set, the server migrates only if it is production, and otherwise starts only on a current schema.

The server refuses to start on an invalid or incomplete feature configuration, and it names the variable but never the value. A feature whose variables are unset stays off, and its routes answer 503, except the login server's, which do not exist without FAUCET_PUBLIC_URL.

Scheduled routes

Faucet sends nothing on its own between requests. A scheduler calls these with Authorization: Bearer <CRON_SECRET>:

Route Suggested schedule What it does
GET /cron/deliver every minute Sends due webhooks to subscribers and retries failed ones.
GET /cron/redeliver every 10 minutes Asks GitHub to resend webhooks that faucet failed to store.
GET /cron/purge hourly Deletes events past retention, and expired subscriptions.

vercel.json sets these schedules for Vercel Cron.

Deploy

Faucet runs anywhere that runs a Go binary next to Postgres. This repository deploys to Vercel with Neon Postgres. docs/deploy.md has the setup, plus the runbooks for credential rotation, rollbacks and database restores.

Embed it

The packages:

  • faucet: the core. faucet.New builds a Service. Mount Service.WebhookHandler() on your router. Build your *mcp.Server with mcp.ServerOptions{Capabilities: faucet.ServerCapabilities()}, call Service.Register on it, and wrap its HTTP handler in faucet.RequireEventName, which checks the Mcp-Name header. Bring your own Authorizer and principal lookup, or use TokenAuthorizer (see docs/security.md for the principal kinds and the scopes).
  • faucet/redelivery: the failed-webhook sweep, built with redelivery.New.
  • faucet/pgstore: the Postgres store, with embedded migrations.
  • faucet/storetest: the contract tests that every Store must pass.
  • faucet/oauth: faucet's login server for service clients: the token endpoint and its metadata, the clients and their repo grants, and the access tokens that it mints.

cmd/faucet is the reference host and wires all of it together. The host decides who may call Service.Purge, Service.DeliverDue and Runner.Run, and when.

Docs

  • docs/events.md: the event names, their actions and filters, and the GitHub webhook to set up.
  • docs/webhooks.md: the contract for a callback receiver (signatures, retries, cursors, control messages, secret rotation).
  • docs/redelivery.md: how failed GitHub deliveries are recovered, with the sweep's guarantees, capacity and known limits.
  • docs/security.md: the access checks, the callback URL guard and secret handling.
  • docs/deploy.md: deploying and operating faucet, and what each scheduled route answers.
  • docs/service-accounts.md: service agents that log in with client credentials, how an operator makes their clients, and how grants match repositories.
  • docs/upgrading.md: what to change on the GitHub hook and during a rolling deploy when you upgrade.

Development

FAUCET_TEST_DATABASE_URL='postgres://postgres@127.0.0.1:5432/postgres?sslmode=disable' go test -race ./...

Each test creates and drops its own database. After you change a migration or a query, run go -C tools tool sqlc generate -f ../sqlc.yaml. The end-to-end checks live in verify/. AGENTS.md has the rules for working on the code.

License

MIT

About

GitHub webhook events for AI agents over MCP: a Go library with a thin server

Resources

Code of conduct

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages