GitHub events for AI agents, over MCP.
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.
- Wait. The
wait_for_github_eventstool long-polls (up to 50 seconds) and returns as soon as a matching event exists. Pass back the returnedcursorto continue with no gaps or repeats. - Poll.
events/listandevents/pollfrom the draft MCP Events extension (SEP-3415). - Subscribe.
events/subscriberegisters 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.
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/faucetThe 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).
| 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.
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.
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.
The packages:
faucet: the core.faucet.Newbuilds aService. MountService.WebhookHandler()on your router. Build your*mcp.Serverwithmcp.ServerOptions{Capabilities: faucet.ServerCapabilities()}, callService.Registeron it, and wrap its HTTP handler infaucet.RequireEventName, which checks theMcp-Nameheader. Bring your ownAuthorizerand principal lookup, or useTokenAuthorizer(see docs/security.md for the principal kinds and the scopes).faucet/redelivery: the failed-webhook sweep, built withredelivery.New.faucet/pgstore: the Postgres store, with embedded migrations.faucet/storetest: the contract tests that everyStoremust 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/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.
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.