RoboMP: GitHub Triage Bot
Relevant source files
The following files were used as context for generating this wiki page:
RoboMP is a self-hosted GitHub triage-and-fix bot designed to automate the lifecycle of GitHub issues and pull requests. It operates as an orchestrator that drives the omp (Oh My Pi) coding harness in RPC mode to perform autonomous tasks such as issue classification, reproduction, bug fixing, and documentation updates. The system is built to provide "load-bearing" changes with engineering rigor, ensuring that every action is grounded in source code and repo conventions.
The bot follows a structured workflow: it classifies incoming issues, applies relevant labels, and then branches into specific task paths such as reproducing and fixing bugs, answering questions, or engaging with proposals. It utilizes a durable event state backed by SQLite and runs within a Docker environment, ensuring that interrupted tasks can resume their prior reasoning through persistent session directories.
Sources: python/robomp/AGENTS.md:3-8, python/robomp/src/prompts/system_append.md:1-5
System Architecture
RoboMP's architecture is built on a durable pipeline that handles webhooks and dispatches work to isolated environments.
Data Flow and Components
- Webhook Ingestion: GitHub webhooks are received via a FastAPI server, verified using HMAC-SHA256, and routed based on the event type (issue, comment, PR review).
- Durable Queue: Events are recorded in a SQLite database to ensure idempotency and durability. A worker pool claims queued events for processing.
- Sandbox Management: Each task runs in a dedicated git worktree. This environment is isolated, using a shared clone pool to minimize disk usage while maintaining a clean state for every issue.
- Worker Execution: The worker spawns an
omp --mode rpcsubprocess. It passes the worktree context and a persistent session directory, allowing the agent to "continue" reasoning across follow-up events or restarts.
The diagram shows the high-level flow from a GitHub event to execution within an isolated sandbox.
Sources: python/robomp/AGENTS.md:12-25
Key System Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| Server | FastAPI application handling webhooks and dashboard. | src/server.py |
| WorkerPool | Async dispatcher that serializes per-issue work and manages concurrency. | src/queue.py |
| SandboxManager | Manages git worktrees and isolated environments for agents. | src/sandbox.py |
| Worker | Synchronous driver for the omp RPC subprocess; assembles prompts. | src/worker.py |
| Host Tools | The only surface allowed to mutate GitHub or write audit logs. | src/host_tools.py |
Sources: python/robomp/AGENTS.md:106-120
Triage and Classification
Classification is the mandatory first step for any new issue. RoboMP uses a specific taxonomy to determine the subsequent workflow.
Classification Taxonomy
Issues are assigned exactly one primary label and multiple optional functional/priority labels.
| Label | Intent | Action |
|---|---|---|
bug | Existing behavior is broken. | Repro + Fix + PR. Requires priority. |
documentation | Docs are missing or outdated. | Fix + PR. |
enhancement | Feature request. | Discussion only; no implementation uninvited. |
question | Usage/How-to question. | Answer in a single comment. |
proposal | Design/Process proposal. | Comment with thoughts. |
invalid / duplicate | Off-topic or redundant. | Brief explanatory comment. |
Sources: python/robomp/src/prompts/system_append.md:15-32
Triage Sequence
The diagram illustrates that triage must precede any other side-effect on GitHub.
Sources: python/robomp/src/prompts/system_append.md:3-5
Automated Bug-Fix Workflow
For issues classified as bug or documentation, RoboMP follows a rigorous 10-step autonomous workflow to resolve the issue.
Execution Phases
- Acknowledgement: Posts a brief comment indicating investigation has started.
- Reproduction: Builds a minimal reproduction case and records the outcome using
repro_record. - Diagnosis: Locates the root cause in the source code.
- Fix: Implements the smallest possible diff to address the cause, including regression tests.
- Verification: Runs affected tests and ensures a green state.
- Polish: Runs repository formatters (e.g.,
bun run fix). - Commit: Generates conventional commits (e.g.,
fix(scope): description) referencing the issue. - Publish: Pushes the branch and opens a Pull Request via host tools.
- Link: Posts a final comment linking the PR to the issue.
Sources: python/robomp/src/prompts/system_append.md:46-64
Pre-Publish Gates
Before pushing a branch or opening a PR, the system enforces a "Two-strikes rule" and automated checks.
- Mandatory Checks:
gh_push_branchandgh_open_prdeterministically runbun run fixandbun check. - Skip Policy:
skip_checks=trueis strictly reserved for pre-existing breakage on themainbranch, which must be verified by the agent.
Sources: python/robomp/src/prompts/system_append.md:65-75
Pull Request Review System
RoboMP also functions as a read-only code reviewer. It classifies, ranks, and comments on PRs to help maintainers make one-glance decisions.
Review Ranking (P0-P3)
The bot assigns a rank based on value, scope discipline, and convention adherence.
- P0 (LGTM): Nicely scoped, follows conventions, can be merged immediately.
- P1: Mergeable after minor nits or architectural notes.
- P2: Requires a maintainer call (e.g., changing default behaviors).
- P3: Badly scoped, broken, or already resolved.
Sources: python/robomp/src/prompts/kickoff_pr_review.md:38-51
Review Phases
RoboMP batches all inline comments into a single review submission to minimize notification noise.
Sources: python/robomp/src/prompts/kickoff_pr_review.md:15-25
Development and Configuration
Essential Environment Variables
RoboMP configuration is managed via Pydantic settings with a ROBOMP_ prefix.
| Variable | Description | Default / Required |
|---|---|---|
GITHUB_WEBHOOK_SECRET | Secret for HMAC verification. | Required |
ROBOMP_BOT_LOGIN | The GitHub handle of the bot. | Required |
ROBOMP_REPO_ALLOWLIST | List of repositories the bot is allowed to touch. | Required |
ROBOMP_MODEL | CSV pool of LLM models for the worker to pick from. | Required |
ROBOMP_MAX_CONCURRENCY | Maximum simultaneous worker tasks. | 8 |
Sources: python/robomp/AGENTS.md:162-170
Operational Commands
Developers interact with RoboMP using bun recipes from the monorepo root.
# Start the server locally
bun run robomp:serve
# Build and run with Docker Compose
bun run robomp:build
bun run robomp:dev
# Manual triage of a specific issue
docker compose exec robomp robomp triage owner/repo#N
Sources: python/robomp/AGENTS.md:65-90
Conclusion
RoboMP: GitHub Triage Bot provides a robust, autonomous framework for managing GitHub repositories. By integrating the Oh My Pi (omp) harness with a durable FastAPI/SQLite backend and isolated git sandboxes, it ensures that AI-driven code changes are high-quality, reproducible, and compliant with project standards. Its tiered triage system and batched PR review logic enable efficient collaboration between human maintainers and the autonomous agent.