Skip to content

Contributing

Jump to bottom
AgenticMail edited this page May 18, 2026 · 1 revision

Contributing

agenticmail/github-app has the bot installed on itself. Every issue and PR you open exercises the production code, so you'll experience the bot the same way any user does.

Filing an issue

Open one the usual way: Issues → New issue. Within ~15 seconds the bot auto-triages it — a comment lands with suggested labels, a priority, and a duplicate-check.

The triage is advisory. The bot suggests, you (or a maintainer) decide. If the labels are off, ignore them.

You can also call the bot yourself in a comment:

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

Good first issue checklist:

  • ✅ Repro steps if it's a bug
  • ✅ Expected vs actual behavior
  • ✅ Webhook delivery UUID from the audit log if you have one (helps cross-reference with our function logs)
  • ❌ Don't paste private comment content — the function never persists it but issue bodies are public on the repo

Sending a pull request

gh repo fork agenticmail/github-app --clone
cd github-app
git checkout -b feat/your-feature
# ... your changes ...
git push -u origin feat/your-feature
gh pr create

When you open the PR:

  1. Auto-summary fires in ~15 seconds. The bot pulls in the diff from up to 20 changed files (first 40 lines of each patch). For most PRs this is enough — the bot's summary will reflect what actually changed, not just the description.

  2. Request a deeper read at any time:

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

  3. The bot never auto-approves or auto-merges. @agenticmail merge is a paid command and requires a human to type it.

Code-quality expectations

The webhook function lives at agenticmail/frontend/netlify/functions/github-webhook.mts. The parser

  • verb sets live at agenticmail/frontend/netlify/functions/_lib/parse-mention.ts for testability.

Before sending a PR:

cd frontend
npm install
npx tsc --noEmit            # types must clean
npm test                    # vitest, 17 tests around parseMention

CI runs the same checks on every PR via agenticmail/frontend/.github/workflows/test.yml.

If your change touches the LLM prompt, add a comment in generateReply() explaining why. Prompt regressions are silent and expensive — make the intent obvious so the next person doesn't undo your work.

Rate limits

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

If you genuinely need higher limits for a contribution session, ping a maintainer — we can comp the installation to a paid plan temporarily via /api/github/billing.

When the bot says something wrong

Just ignore the comment and reply normally. The bot's reply is a draft, not source of truth.

If a comment is misleading enough to need removing, leave a 👎 reaction on it. Maintainers audit those cases periodically and may adjust the prompt or model parameters.

Bug-report template

If you're filing a bot-misbehavior bug, the auto-triage will pick this up — but it helps to include:

**What I did:**
@agenticmail <verb> ... (in issue/PR #N on repo X)

**Expected:**
<what should happen>

**Actual:**
<what happened, paste the bot's comment if any>

**Audit log delivery UUID (if available):**
<from /api/github/audit, helps cross-ref function logs>

**Anything strange in the thread:**
<edited comments, very long threads, weird unicode, etc>

Code of conduct

Be kind. The bot will probably misbehave eventually; complaining at the bot is fine, complaining at humans isn't. We're all here trying to ship.

Clone this wiki locally