AgenticMail for GitHub

Mention @agenticmail in any issue or pull request and an AgenticMail agent reads the thread, does the work, and replies — right inside GitHub.

[ hero GIF — see docs/screenshots/hero.gif ]

---

What it does

AgenticMail for GitHub is a mention bot. Drop @agenticmail into a comment on any issue or PR and the App invokes an AgenticMail agent against that thread. The agent posts its result back as a comment — usually within a couple of seconds, after dropping a 👀 reaction so you know it's working.

It also runs automatically on new issues (triage) and new PRs (summary), so your backlog gets a first pass without anyone lifting a finger.

No new infrastructure: the App mounts as a route on your existing AgenticMail deployment and reuses the agent runtime you already run.

---

Install

From GitHub Marketplace (recommended)

1. Open AgenticMail on the Marketplace (or jump straight to the install page at github.com/apps/agenticmail).
2. Click Install it for free.
3. Choose the account/org, then pick All repositories or a specific set.
4. Approve the requested permissions (see below) and confirm.

That's it — the bot is live on the repos you selected. The bot proves itself the first time you @agenticmail it (or open a new issue / PR, which it will auto-triage and auto-summarize respectively).

[ install screen — see docs/screenshots/install.png ]

Permissions requested

Scope	Access	Why
Issues	Read/Write	Read thread context, post comments & reactions
Pull requests	Read/Write	Summarize PRs, post review-comment replies
Metadata	Read	Required by GitHub for any App

The bot suggests issue labels in a comment — it does not apply or remove labels, close issues, or push code. Triage is advisory in v1.

---

Use

In any issue or PR comment, type @agenticmail followed by a verb.

Free plan — read + AI-reply commands:

Command	What happens
@agenticmail summarize	Posts a 2-paragraph summary of the thread.
@agenticmail triage	Suggests labels, a priority, and similar issues.
@agenticmail email <addr>	Sends the thread context to a real inbox via AgenticMail.
@agenticmail reply <prompt>	Drafts a follow-up comment from your prompt.
@agenticmail handoff to <agent>	Re-routes the request to another agent in your org.
@agenticmail link related	Finds and links related open issues by similarity.

Paid plan — state-changing actions (require an active paid subscription):

Command	What happens
@agenticmail close [not planned]	Closes the issue or PR. Use not planned for non-completed reasons.
@agenticmail merge [squash|rebase|merge]	Merges the pull request. Default: squash.
@agenticmail review	Posts a formal Pull Request Review (event: COMMENT) with AI-generated feedback. Never auto-approves.

If a paid command is invoked from a free-plan account, the bot replies with an upgrade prompt linking to the Marketplace listing. No state changes occur.

Notes:

• A bare @agenticmail with no verb defaults to summarize.
• An unknown verb posts a short help comment — no agent call is made.
• Only the first@agenticmail mention in a comment is acted on.
• Comments from bots are ignored (loop guard).

Runs automatically

• New issue opened → triage runs and posts suggested labels + priority.
• New PR opened → summarize runs against the description and diff stat.

[ example reply — see docs/screenshots/comment.png ]

---

For operators — deploying the App

The hosted App at github.com/apps/agenticmail runs on Netlify Functions. The same code can be re-deployed under any other GitHub App by setting the four env vars below — the function itself is infrastructure-agnostic (works on any platform that delivers Request/ Response and supports context.waitUntil).

Production endpoints

Route	Purpose
POST /api/github/webhook	Receives all GitHub webhook deliveries.
GET /api/github/health	Liveness + which secrets are configured.
GET /api/github/audit	Operator-only audit log reader (admin-token gated).
GET /api/github/usage	Per-installation token + cost aggregator (admin-token gated).
GET|POST|DELETE /api/github/billing	Inspect / comp / clear plan records (admin-token gated).

GitHub App settings

When you register the App at Settings → Developer settings → GitHub Apps:

• Webhook URL:https://<your-host>/api/github/webhook
• Webhook secret: a strong random string (set it on the App and in env as GITHUB_WEBHOOK_SECRET).
• Permissions: Issues R/W, Pull requests R/W, Metadata R.
• Subscribe to events:issue_comment, pull_request_review_comment, issues, pull_request, installation, marketplace_purchase.

Environment variables

Var	Required	Purpose
GITHUB_APP_ID	yes	Numeric App ID from the App settings page.
GITHUB_APP_PRIVATE_KEY	yes	PEM-encoded RSA private key (escaped \n ok).
GITHUB_WEBHOOK_SECRET	yes	HMAC secret matching the App's webhook config.
ANTHROPIC_AUTH_TOKEN	one of	Claude OAuth token (sk-ant-oat01-…).
ANTHROPIC_API_KEY	one of	Classic API key (sk-ant-api03-…).
ADMIN_AUDIT_TOKEN	no	Enables /api/github/audit, /usage, /billing.
SENDGRID_API_KEY	no	Preferred outbound email path (welcome + ops).
SENDGRID_FROM_EMAIL	no	Verified sender address for SendGrid.
AGENTICMAIL_SEND_URL	no	Fallback email path (any POST-JSON-compatible provider).
AGENTICMAIL_API_KEY	no	API key for the fallback email path.
AGENTICMAIL_OPS_EMAIL	no	Recipient for operator-side install notifications.

The function reads ANTHROPIC_AUTH_TOKEN first; if absent it falls back to ANTHROPIC_API_KEY. OAuth tokens require model claude-haiku-4-5 or higher — earlier-generation aliases like claude-3-5-haiku-latest are not visible on the OAuth surface.

Rate limiting + audit

Every accepted delivery writes one entry to the github-webhook-audit Netlify Blob store, keyed by <YYYY-MM-DD>/<delivery-uuid>. User-triggered mentions are bucketed at 60 per installation per rolling hour — the bot posts a polite cooldown comment once a bucket is exhausted.

Build & run

npm install
npm run typecheck # tsc --noEmit
npm run build # compiles to dist/

A sample webhook payload for local testing lives at scripts/fixture-issue-comment.json.

---

How it works

GitHub comment → POST /webhooks/github
├─ verify HMAC (timing-safe)
├─ dedup on X-GitHub-Delivery UUID
└─ enqueue + 202 in <100ms
│
async worker
├─ 👀 reaction on the trigger comment (~1s)
├─ parse mention → verb + args
├─ fetch thread context via Octokit
├─ invoke agent runtime (inject-message)
└─ post the agent's reply as a comment

The webhook never blocks on agent work — GitHub gets its 202 immediately and all the real work happens off the request path. See design.md for the full API contract.

Security

• HMAC-SHA256 verification on every webhook, constant-time compared.
• Delivery-UUID dedup (5-min TTL) so GitHub retries never double-post.
• Short-lived (~60 min) per-installation tokens, minted on demand from the App's private key — never persisted.
• Per-installation rate limiting (60 user-mentions / hour) to cap abuse impact.
• Bot-authored comments are ignored on inbound (no self-mention loops).

---

Contributing

This repo eats its own dog food — AgenticMail is installed on agenticmail/github-app, so every contribution gets the same automated treatment any user does. Useful while filing issues or sending PRs:

Opening an issue

Open one the usual way (Issues → New issue). Within ~15 seconds the bot will auto-triage it: a comment lands suggesting labels, a priority, and whether it looks like a duplicate of anything in the thread. Treat that as a starting point — the bot suggests labels, it doesn't apply them. If the triage is off, ignore it and re-state the bug.

You can also call the bot yourself in any comment:

@agenticmail summarize # re-summarize after a long discussion
@agenticmail link related # find related open issues
@agenticmail triage # re-triage after the description changes

Sending a pull request

1. Fork, branch, commit, push, open the PR. gh pr create works fine.

2. The bot auto-summarizes every new PR within ~15 seconds. The summary pulls in the diff from up to 20 changed files (first 40 lines of each patch) so the description doesn't have to do the heavy lifting.

3. In any PR comment, you can request a deeper read:

   @agenticmail review # AI-generated PR review (COMMENT event)
   @agenticmail summarize # re-run the summary
   @agenticmail reply explain the rate limiter change in plain English
   

   review posts a formal Pull Request Review with event: COMMENT — it never auto-approves or requests changes. A human still has to merge.

Rate limits

The bot is rate-limited to 60 mentions per installation per rolling hour. If you hit it, the bot posts a polite cooldown comment with the ETA — wait for the reset, then continue.

When the bot says something wrong

Just ignore the comment and reply normally — the bot's reply is a draft, not the source of truth. If a comment is misleading enough to need removing, leave a 👎 reaction so we can audit those cases.

What the bot can and cannot do here

Capability	Available on this repo
Summarize, triage, reply, email, handoff, link	✅ Free, always on
Auto-triage on new issues / auto-summary on new PRs	✅ Always on
Close issues or PRs	✅ (paid-plan-only feature; agenticmail org is comped)
Merge PRs	✅ — but the bot never merges without an explicit @agenticmail merge
Review PRs	✅ — posts a COMMENT review, never an auto-approve

If you'd rather the bot stay out of a specific thread, just don't @agenticmail it. The auto-triage / auto-summary still fires once on open — there's no per-thread opt-out yet.

---

Related

• agenticmail/send-email-action — send email straight from a GitHub Actions workflow step. Different tool, same family: that's for CI pipelines, this is for issue/PR conversations.

---

License

MIT © AgenticMail