{"id":51354186,"url":"https://github.com/agenticmail/github-app","last_synced_at":"2026-07-02T18:10:53.795Z","repository":{"id":358565375,"uuid":"1241707091","full_name":"agenticmail/github-app","owner":"agenticmail","description":"AgenticMail for GitHub — @agenticmail mention bot for issues and PRs. Install on any repo to invoke AI agents inline.","archived":false,"fork":false,"pushed_at":"2026-05-18T00:21:46.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T02:39:02.422Z","etag":null,"topics":["agenticmail","ai-agents","claude","codex","github-app","github-marketplace","hono","mcp","mention-bot","octokit","webhook"],"latest_commit_sha":null,"homepage":"https://agenticmail.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agenticmail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T18:06:12.000Z","updated_at":"2026-05-18T00:21:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agenticmail/github-app","commit_stats":null,"previous_names":["agenticmail/github-app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/agenticmail/github-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticmail%2Fgithub-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticmail%2Fgithub-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticmail%2Fgithub-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticmail%2Fgithub-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agenticmail","download_url":"https://codeload.github.com/agenticmail/github-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticmail%2Fgithub-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35057581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agenticmail","ai-agents","claude","codex","github-app","github-marketplace","hono","mcp","mention-bot","octokit","webhook"],"created_at":"2026-07-02T18:10:50.245Z","updated_at":"2026-07-02T18:10:53.778Z","avatar_url":"https://github.com/agenticmail.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgenticMail for GitHub\n\n\u003e Mention `@agenticmail` in any issue or pull request and an AgenticMail agent\n\u003e reads the thread, does the work, and replies — right inside GitHub.\n\n\u003c!-- screenshot:hero --\u003e\n\u003c!-- PLACEHOLDER — 1280×640 hero GIF: a user types \"@agenticmail summarize\"\n     in an issue comment, the bot reacts 👀, then posts a 2-paragraph summary.\n     File: docs/screenshots/hero.gif --\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003e[ hero GIF — see docs/screenshots/hero.gif ]\u003c/em\u003e\u003c/p\u003e\n\n[![Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-AgenticMail-2da44e)](https://github.com/marketplace/agenticmail)\n[![Price](https://img.shields.io/badge/price-free-2da44e)](https://github.com/marketplace/agenticmail)\n[![Install](https://img.shields.io/badge/install-1%20click-2da44e)](https://github.com/apps/agenticmail)\n\n---\n\n## What it does\n\nAgenticMail for GitHub is a mention bot. Drop `@agenticmail` into a comment on\nany issue or PR and the App invokes an AgenticMail agent against that thread.\nThe agent posts its result back as a comment — usually within a couple of\nseconds, after dropping a 👀 reaction so you know it's working.\n\nIt also runs **automatically** on new issues (triage) and new PRs (summary), so\nyour backlog gets a first pass without anyone lifting a finger.\n\nNo new infrastructure: the App mounts as a route on your existing AgenticMail\ndeployment and reuses the agent runtime you already run.\n\n---\n\n## Install\n\n### From GitHub Marketplace (recommended)\n\n1. Open **[AgenticMail on the Marketplace](https://github.com/marketplace/agenticmail)**\n   (or jump straight to the install page at **[github.com/apps/agenticmail](https://github.com/apps/agenticmail)**).\n2. Click **Install it for free**.\n3. Choose the account/org, then pick **All repositories** or a specific set.\n4. Approve the requested permissions (see below) and confirm.\n\nThat's it — the bot is live on the repos you selected. The bot proves itself\nthe first time you `@agenticmail` it (or open a new issue / PR, which it\nwill auto-triage and auto-summarize respectively).\n\n\u003c!-- screenshot:install --\u003e\n\u003c!-- PLACEHOLDER — 1280×800 PNG of the Marketplace install screen.\n     File: docs/screenshots/install.png --\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003e[ install screen — see docs/screenshots/install.png ]\u003c/em\u003e\u003c/p\u003e\n\n### Permissions requested\n\n| Scope          | Access     | Why                                          |\n| -------------- | ---------- | -------------------------------------------- |\n| Issues         | Read/Write | Read thread context, post comments \u0026 reactions |\n| Pull requests  | Read/Write | Summarize PRs, post review-comment replies   |\n| Metadata       | Read       | Required by GitHub for any App               |\n\nThe bot **suggests** issue labels in a comment — it does **not** apply or remove\nlabels, close issues, or push code. Triage is advisory in v1.\n\n---\n\n## Use\n\nIn any issue or PR comment, type `@agenticmail` followed by a verb.\n\n**Free plan** — read + AI-reply commands:\n\n| Command                          | What happens                                              |\n| --------------------------------- | --------------------------------------------------------- |\n| `@agenticmail summarize`          | Posts a 2-paragraph summary of the thread.                |\n| `@agenticmail triage`             | Suggests labels, a priority, and similar issues.          |\n| `@agenticmail email \u003caddr\u003e`       | Sends the thread context to a real inbox via AgenticMail. |\n| `@agenticmail reply \u003cprompt\u003e`     | Drafts a follow-up comment from your prompt.               |\n| `@agenticmail handoff to \u003cagent\u003e` | Re-routes the request to another agent in your org.       |\n| `@agenticmail link related`       | Finds and links related open issues by similarity.        |\n\n**Paid plan** — state-changing actions (require an active paid subscription):\n\n| Command                          | What happens                                              |\n| --------------------------------- | --------------------------------------------------------- |\n| `@agenticmail close [not planned]`| Closes the issue or PR. Use `not planned` for non-completed reasons. |\n| `@agenticmail merge [squash\\|rebase\\|merge]` | Merges the pull request. Default: `squash`. |\n| `@agenticmail review`             | Posts a formal Pull Request Review (`event: COMMENT`) with AI-generated feedback. Never auto-approves. |\n\nIf a paid command is invoked from a free-plan account, the bot replies with an\nupgrade prompt linking to the Marketplace listing. No state changes occur.\n\nNotes:\n- A bare `@agenticmail` with no verb defaults to **summarize**.\n- An unknown verb posts a short help comment — no agent call is made.\n- Only the **first** `@agenticmail` mention in a comment is acted on.\n- Comments from bots are ignored (loop guard).\n\n### Runs automatically\n\n- **New issue opened** → `triage` runs and posts suggested labels + priority.\n- **New PR opened** → `summarize` runs against the description and diff stat.\n\n\u003c!-- screenshot:comment --\u003e\n\u003c!-- PLACEHOLDER — 1280×720 PNG of a posted summarize comment with the\n     \"— AgenticMail · summarize\" footer.\n     File: docs/screenshots/comment.png --\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003e[ example reply — see docs/screenshots/comment.png ]\u003c/em\u003e\u003c/p\u003e\n\n---\n\n## For operators — deploying the App\n\nThe hosted App at [github.com/apps/agenticmail](https://github.com/apps/agenticmail)\nruns on Netlify Functions. The same code can be re-deployed under any other\nGitHub App by setting the four env vars below — the function itself is\ninfrastructure-agnostic (works on any platform that delivers `Request`/\n`Response` and supports `context.waitUntil`).\n\n### Production endpoints\n\n| Route                          | Purpose                                          |\n| ------------------------------- | ------------------------------------------------ |\n| `POST /api/github/webhook`     | Receives all GitHub webhook deliveries.          |\n| `GET  /api/github/health`      | Liveness + which secrets are configured.         |\n| `GET  /api/github/audit`       | Operator-only audit log reader (admin-token gated). |\n| `GET  /api/github/usage`       | Per-installation token + cost aggregator (admin-token gated). |\n| `GET\\|POST\\|DELETE /api/github/billing` | Inspect / comp / clear plan records (admin-token gated). |\n\n### GitHub App settings\n\nWhen you register the App at **Settings → Developer settings → GitHub Apps**:\n\n- **Webhook URL:** `https://\u003cyour-host\u003e/api/github/webhook`\n- **Webhook secret:** a strong random string (set it on the App and in env as `GITHUB_WEBHOOK_SECRET`).\n- **Permissions:** Issues R/W, Pull requests R/W, Metadata R.\n- **Subscribe to events:** `issue_comment`, `pull_request_review_comment`,\n  `issues`, `pull_request`, `installation`, `marketplace_purchase`.\n\n### Environment variables\n\n| Var                          | Required | Purpose                                          |\n| ----------------------------- | -------- | ------------------------------------------------ |\n| `GITHUB_APP_ID`              | yes      | Numeric App ID from the App settings page.       |\n| `GITHUB_APP_PRIVATE_KEY`     | yes      | PEM-encoded RSA private key (escaped `\\n` ok).   |\n| `GITHUB_WEBHOOK_SECRET`      | yes      | HMAC secret matching the App's webhook config.   |\n| `ANTHROPIC_AUTH_TOKEN`       | one of   | Claude OAuth token (`sk-ant-oat01-…`).           |\n| `ANTHROPIC_API_KEY`          | one of   | Classic API key (`sk-ant-api03-…`).              |\n| `ADMIN_AUDIT_TOKEN`          | no       | Enables `/api/github/audit`, `/usage`, `/billing`. |\n| `SENDGRID_API_KEY`           | no       | Preferred outbound email path (welcome + ops).   |\n| `SENDGRID_FROM_EMAIL`        | no       | Verified sender address for SendGrid.            |\n| `AGENTICMAIL_SEND_URL`       | no       | Fallback email path (any POST-JSON-compatible provider). |\n| `AGENTICMAIL_API_KEY`        | no       | API key for the fallback email path.             |\n| `AGENTICMAIL_OPS_EMAIL`      | no       | Recipient for operator-side install notifications. |\n\nThe function reads `ANTHROPIC_AUTH_TOKEN` first; if absent it falls back\nto `ANTHROPIC_API_KEY`. OAuth tokens require model `claude-haiku-4-5`\nor higher — earlier-generation aliases like `claude-3-5-haiku-latest`\nare not visible on the OAuth surface.\n\n### Rate limiting + audit\n\nEvery accepted delivery writes one entry to the `github-webhook-audit`\nNetlify Blob store, keyed by `\u003cYYYY-MM-DD\u003e/\u003cdelivery-uuid\u003e`. User-triggered\nmentions are bucketed at **60 per installation per rolling hour** — the bot\nposts a polite cooldown comment once a bucket is exhausted.\n\n### Build \u0026 run\n\n```sh\nnpm install\nnpm run typecheck      # tsc --noEmit\nnpm run build          # compiles to dist/\n```\n\nA sample webhook payload for local testing lives at\n`scripts/fixture-issue-comment.json`.\n\n---\n\n## How it works\n\n```\nGitHub comment  →  POST /webhooks/github\n                   ├─ verify HMAC (timing-safe)\n                   ├─ dedup on X-GitHub-Delivery UUID\n                   └─ enqueue + 202 in \u003c100ms\n                          │\n                   async worker\n                   ├─ 👀 reaction on the trigger comment (~1s)\n                   ├─ parse mention → verb + args\n                   ├─ fetch thread context via Octokit\n                   ├─ invoke agent runtime (inject-message)\n                   └─ post the agent's reply as a comment\n```\n\nThe webhook never blocks on agent work — GitHub gets its `202` immediately and\nall the real work happens off the request path. See [`design.md`](./design.md)\nfor the full API contract.\n\n### Security\n\n- HMAC-SHA256 verification on every webhook, constant-time compared.\n- Delivery-UUID dedup (5-min TTL) so GitHub retries never double-post.\n- Short-lived (~60 min) per-installation tokens, minted on demand from the\n  App's private key — never persisted.\n- Per-installation rate limiting (60 user-mentions / hour) to cap abuse impact.\n- Bot-authored comments are ignored on inbound (no self-mention loops).\n\n---\n\n## Contributing\n\n**This repo eats its own dog food** — AgenticMail is installed on\n`agenticmail/github-app`, so every contribution gets the same automated\ntreatment any user does. Useful while filing issues or sending PRs:\n\n### Opening an issue\n\nOpen one the usual way (`Issues → New issue`). Within ~15 seconds the bot\nwill auto-triage it: a comment lands suggesting labels, a priority, and\nwhether it looks like a duplicate of anything in the thread. Treat that as\na starting point — the bot **suggests** labels, it doesn't apply them. If\nthe triage is off, ignore it and re-state the bug.\n\nYou can also call the bot yourself in any comment:\n\n```\n@agenticmail summarize       # re-summarize after a long discussion\n@agenticmail link related    # find related open issues\n@agenticmail triage          # re-triage after the description changes\n```\n\n### Sending a pull request\n\n1. Fork, branch, commit, push, open the PR. **`gh pr create` works fine.**\n2. The bot auto-summarizes every new PR within ~15 seconds. The summary\n   pulls in the diff from up to 20 changed files (first 40 lines of each\n   patch) so the description doesn't have to do the heavy lifting.\n3. In any PR comment, you can request a deeper read:\n\n   ```\n   @agenticmail review                       # AI-generated PR review (COMMENT event)\n   @agenticmail summarize                    # re-run the summary\n   @agenticmail reply explain the rate limiter change in plain English\n   ```\n\n   `review` posts a formal Pull Request Review with `event: COMMENT` — it\n   never auto-approves or requests changes. A human still has to merge.\n\n### Rate limits\n\nThe bot is rate-limited to 60 mentions per installation per rolling hour.\nIf you hit it, the bot posts a polite cooldown comment with the ETA — wait\nfor the reset, then continue.\n\n### When the bot says something wrong\n\nJust ignore the comment and reply normally — the bot's reply is a draft,\nnot the source of truth. If a comment is misleading enough to need\nremoving, leave a 👎 reaction so we can audit those cases.\n\n### What the bot can and cannot do here\n\n| Capability | Available on this repo |\n| --- | --- |\n| Summarize, triage, reply, email, handoff, link | ✅ Free, always on |\n| Auto-triage on new issues / auto-summary on new PRs | ✅ Always on |\n| **Close** issues or PRs | ✅ (paid-plan-only feature; agenticmail org is comped) |\n| **Merge** PRs | ✅ — but the bot never merges without an explicit `@agenticmail merge` |\n| **Review** PRs | ✅ — posts a `COMMENT` review, never an auto-approve |\n\nIf you'd rather the bot stay out of a specific thread, just don't\n`@agenticmail` it. The auto-triage / auto-summary still fires once on\nopen — there's no per-thread opt-out yet.\n\n---\n\n## Related\n\n- **[agenticmail/send-email-action](https://github.com/agenticmail/send-email-action)** —\n  send email straight from a GitHub Actions workflow step. Different tool, same\n  family: that's for CI pipelines, this is for issue/PR conversations.\n\n---\n\n## License\n\nMIT © AgenticMail\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenticmail%2Fgithub-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagenticmail%2Fgithub-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenticmail%2Fgithub-app/lists"}