https://github.com/agenticmail/github-app
AgenticMail for GitHub — @agenticmail mention bot for issues and PRs. Install on any repo to invoke AI agents inline.
https://github.com/agenticmail/github-app
agenticmail ai-agents claude codex github-app github-marketplace hono mcp mention-bot octokit webhook
Last synced: 28 days ago
JSON representation
AgenticMail for GitHub — @agenticmail mention bot for issues and PRs. Install on any repo to invoke AI agents inline.
- Host: GitHub
- URL: https://github.com/agenticmail/github-app
- Owner: agenticmail
- Created: 2026-05-17T18:06:12.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-18T00:21:46.000Z (2 months ago)
- Last Synced: 2026-05-18T02:39:02.422Z (2 months ago)
- Topics: agenticmail, ai-agents, claude, codex, github-app, github-marketplace, hono, mcp, mention-bot, octokit, webhook
- Language: TypeScript
- Homepage: https://agenticmail.io
- Size: 37.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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 ]
[](https://github.com/marketplace/agenticmail)
[](https://github.com/marketplace/agenticmail)
[](https://github.com/apps/agenticmail)
---
## 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](https://github.com/marketplace/agenticmail)**
(or jump straight to the install page at **[github.com/apps/agenticmail](https://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 ` | Sends the thread context to a real inbox via AgenticMail. |
| `@agenticmail reply ` | Drafts a follow-up comment from your prompt. |
| `@agenticmail handoff to ` | 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](https://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:///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 `/`. 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
```sh
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`](./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](https://github.com/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