Assign an issue to your familiar. Get a PR back.
coven-github is the GitHub App adapter for OpenCoven. It routes GitHub issues, labels, mentions, and review comments into a Coven familiar, then publishes progress through Check Runs, issue comments, draft PRs, and CovenCave session links.
flowchart LR
issue[GitHub issue, label, mention, or review comment]
app[coven-github GitHub App]
worker[coven-github worker]
familiar[coven-code familiar session]
check[GitHub Check Run]
pr[Draft pull request]
cave[CovenCave oversight]
issue --> app
app --> worker
worker --> familiar
worker --> check
familiar --> pr
worker --> cave
check --> reviewer[Maintainer]
pr --> reviewer
cave --> reviewer
- Accepts GitHub App webhook deliveries and verifies their HMAC signature.
- Routes configured triggers to a familiar by bot username or label.
- Runs
coven-code --headlesswith a tokenless session brief. - Posts Check Run state, direct Cave session links, and draft PRs when the run produces commits.
- Runs the Branch Gardener on configured schedules or
gardencommands to prune dead branches and surface PRless work.
See Architecture Diagrams, Design, Hosted OpenCoven, Familiar Contract, Roadmap, and Hosted vs self-hosted for the operational plan.
Want to see the whole loop run? examples/demo/run-demo.sh drives the
real adapter through the full operating loop — issue assignment, Check Run,
edited-in-place status comment, maintainer steering commands, permission
gate, familiar-voice draft PR — offline and self-verifying in about a minute.
docs/demo.md narrates it.
flowchart TB
subgraph github[GitHub]
trigger[Issue assignment<br/>trigger label<br/>@mention<br/>review comment]
checks[Check Run]
pull[Draft PR]
end
subgraph adapter[coven-github]
webhook[Webhook receiver<br/>HMAC validation<br/>event parsing]
routing[Familiar routing<br/>bot username<br/>trigger labels]
tasks[Task queue/store<br/>status and audit]
runner[Worker<br/>session brief<br/>timeout enforcement]
end
subgraph runtime[OpenCoven runtime]
session[coven-code --headless]
result[Result envelope<br/>summary, branch, evidence]
end
cave[CovenCave oversight<br/>live session and intervention]
trigger --> webhook
webhook --> routing
routing --> tasks
tasks --> runner
runner --> session
session --> result
result --> runner
runner --> checks
runner --> pull
runner --> cave
For deeper system, sequence, state, security-boundary, and hosted deployment diagrams, read docs/architecture.md.
| Component | Location | Role |
|---|---|---|
crates/webhook |
this repo | Webhook receiver: HMAC validation, event parsing, queue publish |
crates/worker |
this repo | Task runner: spawns coven-code, streams progress, posts Check Runs |
crates/github |
this repo | GitHub API client: installations, Check Runs, PRs, comments |
crates/config |
this repo | Familiar config, installation registry, model routing |
coven-github-webhook |
OpenCoven/coven-github-webhook | TypeScript deployment bundle for the hosted/self-hostable webhook entrypoint |
coven-code |
OpenCoven/coven-code | Execution runtime (headless mode) |
CovenCave |
OpenCoven/coven-cave | Oversight UI |
Implemented lanes:
| Trigger | Action |
|---|---|
Issue assigned to bot user (@cody) |
Agent picks up issue, opens PR |
coven: label applied to issue |
Same as above |
Maintainer command in a comment (@cody <command>) |
See the command table below |
| PR opened / synchronize / reopened / ready_for_review | Automatic hosted review when the [review] policy enables the lane (drafts skipped by default; newer pushes supersede queued reviews of the same PR) |
| Review label applied to a PR | Explicit per-PR review opt-in — works even with the automatic lane off, including drafts |
| Branch Gardener schedule | Enqueues adapter-side branch hygiene for configured installation/repository policies |
Maintainer garden command |
Runs Branch Gardener on demand for the current repository |
Planned lanes:
| Trigger | Status |
|---|---|
| Push / commit-range review | push events are parsed and typed with fixtures today; execution needs a PR-less task kind, which ships with headless contract v3 |
Review findings pass deterministic publication gates before any surface
sees them: out-of-scope files (never consulted by the session), findings below
the repo's min_severity policy, and duplicates are withheld — with the
withheld counts stated in the digest. The [review] publish policy routes the
gated digest to the Check Run (default), additionally to the status comment
(advisory_comment), or as a blocking PR review verdict (request_changes).
A mention only acts when it is the first token of the comment, followed by a
command verb — @cody review, @cody fix: the lint is failing. Casual
mentions mid-sentence trigger nothing, and an unknown verb in command position
gets a clarification reply instead of launching work. Every command except
status requires write access to the repository; the familiar's own
comments never re-trigger it.
| Command | On an issue | On a PR |
|---|---|---|
review |
Clarification (needs a PR) | Hosted review of the PR |
fix [text] |
Fix the issue (opens a PR) | Address the feedback in the comment |
deepen |
Clarification | Re-review with a wider lens (supporting files, tests) |
retry |
Re-run the fix lane | Re-run the review |
cancel |
Clarification (PR reviews only) | Cancel queued reviews for the PR (in-flight work finishes) |
garden |
Run Branch Gardener for the repository | Run Branch Gardener for the repository |
remember / forget |
Acknowledged; persistence lands with the memory governance contract (#6) | Same |
status |
Current task state for this thread | Same |
Each familiar keeps one marker-backed status comment per issue/PR, edited in place through the task lifecycle (working → done / needs input / failed), with links to the Check Run, PR, and Cave session — repeated runs never stack duplicate comments.
🚧 In development. The repo has the first GitHub App adapter path wired, but hosted production readiness is still being built. See COVEN-GITHUB.md for the roadmap-level product spec.
| Capability | Status | Notes |
|---|---|---|
| Webhook HMAC validation | Implemented | Rejects unsigned or invalid GitHub webhook payloads. |
| Issue assignment trigger | Implemented | Routes matching bot assignees to configured familiars. |
| Label trigger | Implemented | Routes configured trigger_labels such as coven:fix. |
| Maintainer command protocol | Implemented | Typed @familiar <verb> grammar; casual mentions ignored; write-access gate; self-comments never re-trigger. |
| Marker-backed status comments | Implemented | One edited-in-place status surface per issue/PR; no duplicate bot comments. |
| Installation-scoped routing | Implemented | [[installations]] policy: per-installation familiar allow-lists, per-repo trigger-lane switches, fail-closed for unlisted installations; absent config keeps open self-hosted routing. |
| Usage metering + tier limits | Implemented | Per-installation max_concurrent (enforced at claim) and max_tasks_per_day (enforced at intake, recorded ignored:quota_exceeded); tenant-scoped GET /api/github/usage rollup by installation/repo/familiar with attempt runtime. |
| Reference demo of the operating loop | Implemented | Offline, self-verifying replay of the full loop with a real adapter binary — see docs/demo.md. |
| Branch Gardener | Implemented | Scheduled and garden command runs classify branches, dry-run or prune dead/merged refs by policy, open draft PRs for PRless branches, and report through Cave-visible task state/status surfaces. |
| PR lifecycle review trigger | Implemented | Policy-gated auto-review on opened/synchronize/reopened/ready_for_review plus label opt-in; familiar-authored PRs are never auto-reviewed. |
| Push / commit review trigger | Partial | Events parsed and typed with fixtures; execution lane needs headless contract v3. |
| GitHub App installation tokens | Implemented | Mints installation access tokens from the App private key. |
| Check Run creation and completion | Implemented | Check Runs attach to the resolved target head SHA; PR reviews re-fetch the head pre-publish and complete as neutral/Stale instead of publishing findings against a moved ref. |
| Headless execution contract | Locked (v1) | Brief, result envelope, exit codes, and git-auth channel are pinned in docs/headless-contract.md with JSON Schemas, golden fixtures, and a conformance test. |
coven-code --headless execution |
Partial | Worker spawns headless sessions with a tokenless session brief and enforces task timeouts; result quality depends on the runtime. |
| Worker container isolation | Implemented | worker.backend = "container" runs each attempt in a fresh hardened container (read-only rootfs, cap-drop ALL, cpu/memory/pids/tmpfs/network limits, env-only token injection, kill-by-name on timeout); hosted posture refuses host execution without explicit opt-in — see docs/container-isolation.md. |
| Pull request creation | Partial | Opens draft PRs from session results against the repository's resolved default/base branch. |
| CovenCave task polling | Implemented | Task API served from the durable store, survives restarts, and is gated by the tenant boundary — token mode fails closed, tenant tokens are installation-scoped, and every read is audited (see docs/security.md). |
| Cave oversight dashboard | Implemented | Tenant-scoped data behind the four Cave views: task history (/api/github/tasks), usage (/api/github/usage), familiar routing (/api/github/routing), and a task-lifecycle audit stream (/api/github/audit) — acceptance, execution/retries/timeout, and PR creation. |
| Durable queue / task store | Implemented | Deliveries deduplicated by X-GitHub-Delivery before GitHub hears success; the SQLite tasks table is the queue (atomic claims, no drop path) and interrupted work is requeued at startup (design). |
| Hosted tier | Planned | See Hosted vs self-hosted. |
| Familiar trust contract | Planned | See Familiar Contract. |
# Clone and build
git clone https://github.com/OpenCoven/coven-github
cd coven-github
cargo build --release
# Configure
cp config/example.toml config/local.toml
# Fill in config/local.toml, then validate it.
# doctor prints one next step for every error or warning.
./target/release/coven-github doctor --config config/local.toml
# Run
./target/release/coven-github serve --config config/local.tomlPrefer containers? A multi-stage Dockerfile and
compose.yaml ship in the repo root.
See docs/self-hosting.md for GitHub App registration, permissions, smoke tests, and troubleshooting. For a minimal familiar route, start from examples/familiar-github-starter.
For a lightweight TypeScript deployment entrypoint that follows this app
contract, use
OpenCoven/coven-github-webhook
with its config/example-policy.json and connection guide.
coven-github is open source and self-hostable. OpenCoven offers a hosted tier for organizations that want managed infra, cloud familiar memory, and multi-familiar routing without running their own workers.
See Hosted OpenCoven and Hosted vs self-hosted for the service shape, security boundaries, and buyer packaging.
- coven-code — execution runtime
- coven-github-webhook — TypeScript webhook deployment bundle
- coven-cave — oversight UI
- cast-codes — local IDE with CastAgent
GPL-3.0 — see LICENSE.