feat: GitHub webhooks → OpenCode agent sessions (plugin + bundled config + agent)

[MathurAditya724]

End-to-end automation for "GitHub issue gets assigned → OpenCode resolves it → opens PR", implemented as an OpenCode plugin that loads inside the long-lived opencode server process.

Once you set GITHUB_WEBHOOK_SECRET on a deploy, this image:

1. Opens a webhook listener on port 5050
2. Verifies inbound issues.assigned deliveries against your HMAC secret
3. Spawns an opencode agent session running github-issue-resolver against the right repo
4. The agent clones the repo, branches, plans, implements, pushes, and opens a PR — all without further input

Note: branch is add-hono-sidecar because this PR originally implemented the same goal as a Bun+Hono sidecar process. Once we confirmed plugins load into the host server (with an in-process SDK client), the sidecar approach was dropped in favor of the simpler plugin design. Branch name kept to preserve the PR URL.

What's bundled

File	Role
plugins/github-webhooks.ts (~510 lines)	The plugin. Opens a Bun.serve listener on WEBHOOK_PORT (default 5050). Verifies X-Hub-Signature-256, dedups on X-GitHub-Delivery, dispatches matching triggers via ctx.client.session.create + ctx.client.session.prompt. Concurrency cap (default 2), per-session timeout (default 30 min), retention cap (default 1000 dedup rows).
agents/github-issue-resolver.md	The bundled primary agent. Walks an issue from "assigned" to "PR opened" using the bundled gh + git CLIs. Authenticated via GH_TOKEN. Includes defensive working-tree reset for re-using cloned repos across runs.
webhooks.json	Default trigger config baked into the image. One trigger: issues.assigned → github-issue-resolver. The prompt template interpolates repo, issue number/title/body/url, assignee, author, and labels.
opencode-config-package.json + opencode-config-bun.lock	Copied to ~/.config/opencode/{package.json,bun.lock} so the plugin's import type { Plugin } resolves at startup. Lockfile committed for reproducible builds.
Dockerfile (+44 LOC)	COPYs all of the above into ~/.config/opencode/ at build time. Runs bun install --frozen-lockfile --production once. Exposes port 5050.
.env.example (+24 LOC)	Documents GITHUB_WEBHOOK_SECRET (the activation switch), WEBHOOKS_CONFIG, WEBHOOK_PORT.
README.md (+103 LOC)	New "GitHub webhooks → agent sessions" section: default behavior, override mechanics (rebuild vs runtime), config schema, field reference table, GitHub webhook UI setup, Railway routing note, health check.

Plugin uses zero npm runtime deps — only Bun built-ins (Bun.serve, bun:sqlite, node:crypto). @opencode-ai/plugin is import type-only.

Architecture

The plugin runs inside opencode's process and uses ctx.client (the in-process SDK client provided by the plugin context) to drive sessions directly. No loopback HTTP, no cold-boot race against opencode's HTTP server, no second process to supervise.

Trade-off: an unhandled rejection in the plugin can crash opencode-web. Mitigated with a top-level unhandledRejection guard, aggressive try/catch at the dispatch boundary, body-size caps, and graceful SIGTERM handling that lets in-flight dispatches drain (with a 25s ceiling).

Trigger config

Stored as JSON. Default path ~/.config/opencode/webhooks.json (the baked-in file); overridable with the WEBHOOKS_CONFIG env var pointing to a path on the persistent ~/dev volume. Not stored in opencode.json because that file's published schema declares experimental.additionalProperties: false.

Multiple triggers can match the same delivery — all matching enabled triggers fire concurrently, capped by max_concurrent. The HMAC secret is intentionally not in the JSON file — kept as GITHUB_WEBHOOK_SECRET env var only.

How it works end-to-end

1. GitHub fires issues.assigned → POST /webhooks/github on port 5050.
2. Plugin enforces 25 MB body size cap (matches GitHub's webhook limit).
3. Plugin verifies HMAC against GITHUB_WEBHOOK_SECRET using timingSafeEqual.
4. Plugin dedups on X-GitHub-Delivery via SQLite. Redeliveries are ack'd as duplicate: true and don't re-fire.
5. Plugin matches (event, action) against the trigger list. Every enabled trigger that matches fires.
6. Each match: render the prompt template against the payload, then invoke the agent via client.session.create + client.session.prompt.
7. The bundled agent runs: git fetch --all --prune → git reset --hard origin/<default> (defensive) → branch → plan → implement → push → gh pr create.

The host opencode server is the system of record for the resulting session — view it in the web UI like any other.

Railway deploy

GITHUB_WEBHOOK_SECRET=<same value as GitHub webhook UI>
GH_TOKEN=<PAT with repo, read:org, workflow scopes>
ANTHROPIC_API_KEY=<or any other LLM provider key>

Railway only generates one HTTP domain per service, so port 5050 needs separate routing — second Railway service pointing at the same image, a TCP proxy, or Cloudflare. The opencode web UI on 4096/$PORT is independent.

Security model

• HMAC verification reads raw body before any JSON parse, prefix-checks sha256=, length-equality before timingSafeEqual.
• 25 MB body cap enforced via Content-Length header AND actual rawBody.length (defense in depth).
• Required headers (X-GitHub-Event, X-GitHub-Delivery) enforced before HMAC, so non-GitHub sources can't synthesize delivery IDs to flood the dedup table or match event: "*" rules.
• Idempotent on redelivery — dispatch only fires when SQLite INSERT...ON CONFLICT DO NOTHING actually inserted.
• Concurrency cap prevents trigger fan-out from blowing through token budgets.
• Per-session timeout (default 30 min) aborts runaway agents; the underlying setTimeout is unref()'d so it doesn't hold the event loop past intentional shutdown.
• Graceful SIGTERM/SIGINT (registered with process.once to avoid listener accumulation): closes the listening socket immediately, drains in-flight dispatches with a 25s ceiling.

Verified

Standalone harness with a mock SDK client. Tests exercise:

• Missing X-GitHub-Event / X-GitHub-Delivery → 400 ✓
• Bad HMAC → 401 ✓
• 26 MB body → 413 before HMAC ✓
• Valid first delivery → 200, dispatches every matching trigger ✓
• Redelivery of same delivery_id → 200, duplicate:true, dispatched:[], no extra SDK calls ✓
• 6-trigger config (specific, event-only, catch-all, mismatched, disabled): exactly the 3 matching triggers fire ✓
• SIGTERM → drain log fires, Bun.serve socket closes, post-SIGTERM fetch gets ConnectionRefused, process exits cleanly despite pending 30-min abort timers ✓
• Bundled webhooks.json + agent github-issue-resolver: realistic issues.assigned payload renders correctly into the prompt template ✓
• tsc --noEmit clean.

Commits

fd07425	Initial plugin + agent + bundled config
cff9a3d	Review fixes: matching semantics (drop dead priority/sort), null normalization, dbPath default to ~/dev/.opencode/, log message clarity, graceful shutdown
3ee264c	Bundle default webhooks.json so the feature works the moment GITHUB_WEBHOOK_SECRET is set
9b0769b	Hardening pass: timer.unref() for clean exit, 25 MB body cap, process.once handlers, frozen lockfile, defensive working-tree reset in agent, README example clarification, comment cleanup

Out of scope / follow-ups

• No HTTP API for managing triggers at runtime. Triggers live in a JSON file; editing them requires either a rebuild or repointing WEBHOOKS_CONFIG at a writable path on the volume + restart.
• No streaming session output back to a webhook caller. The plugin awaits session.prompt to completion; for very long-running agents you'd want client.event.subscribe and an SSE relay.
• Process isolation is weaker than a separate sidecar would provide — a plugin bug crashing opencode-web takes the web UI down. Mitigated but not eliminated.
• Branch name is add-hono-sidecar (legacy from prior design). Rename out-of-scope; PR URL stays.