Onboarding
First-time contributor flows
Detects first-time contributors, posts a welcome checklist, validates account age and public-repo count before /assign, and round-robins mentor assignment.
Self-hosted GitHub App · MIT
Maintainer-ops for open source, on your own infrastructure.
PR health scoring, reviewer recommendation, contributor progression, and a full audit trail — one system instead of five bots, running on a database you control. No SaaS lock-in, no vendor hosting your repository data.
76 tests passing
MIT license
Python 3.12+
FastAPI · async SQLAlchemy
Postgres or SQLite
The problem
Maintainer triage lives in someone's head until they burn out.
What gets lost
Every healthy open-source project runs into the same bottleneck: a small number of unpaid maintainers doing manual, repetitive triage — checking DCO sign-off, screening first-time contributors, chasing stale issues, deciding who's ready to become a committer, recommending a reviewer who actually knows the file being changed. None of it is written down. It lives in a maintainer's head until they burn out, and then it's gone.
Two camps, neither one fits
- Commercial SaaS bots — Mergify, CodeRabbit, Greptile. Capable, but closed-source. Your repository data, review history, and contributor metrics live on someone else's servers, behind a subscription that can change price or disappear.
- Single-purpose OSS bots — probot apps, stale-bot, welcome-bot. Free and self-hostable, but each solves one narrow problem. No shared data model, no persistent history, nothing that helps a project reason about its own contributor pipeline over time.
Nobody has a self-hosted, open-source system that treats maintainer-ops as a whole — with a real database, an audit trail, and a data model for how contributors grow inside a project, not just whether a single PR passes a gate.
What it does
One bot, the whole maintainer workflow.
A GitHub App built with FastAPI and async SQLAlchemy, tested against the Hiero (Linux Foundation Decentralized Trust) ecosystem and designed to generalize to any GitHub-hosted project via a single YAML config file.
Quality gates
PR quality gates
DCO sign-off, GPG signature, test-file presence, linked-issue requirement, branch naming pattern, max file count — auto-labelled quality: ✅ / ❌.
Scoring
PR health scoring
Every PR scored 0–100 across six configurable, weighted signals: tests, linked issue, description, DCO, approvals, diff size.
Reviewers
Reviewer recommendation
Suggests reviewers based on recent file-history overlap, logged with a reason and a confidence score.
AI review · optional
AI-assisted review
Structured review — summary, verdict, line comments, severity — via the Anthropic SDK. Disabled by default, never required.
Progression
Contributor progression
Tracks merged PRs, reviews given, months active. Computes eligibility for junior-committer → committer → maintainer, and celebrates merge milestones.
Issues
Issue management
Daily stale scan on a cron schedule, auto-unassign on inactivity, label-based escalation to specific teams.
/api/v1
REST API
Query every stored record — audit log, PR health, contributor snapshots, stale-action history, aggregate repo stats.
Nothing is silent
Persistent audit trail
Every bot action — label, comment, assign, close — is written to Postgres or SQLite with a reason. Queryable later, always.
Why it's different
Same problems, a different set of trade-offs.
| Hiero Maintainer Bot | Mergify | CodeRabbit / Greptile | probot / stale-bot / welcome-bot | |
|---|---|---|---|---|
| License / hosting | MIT, self-hosted | Closed-source SaaS | Closed-source SaaS | Open source, but stateless |
| Where your data lives | Your own Postgres / SQLite | Vendor's servers | Vendor's servers | N/A (no persistence) |
| Contributor role progression | ✅ built-in model | — | — | — |
| PR health scoring | ✅ weighted & configurable | Partial (merge rules only) | — | — |
| AI review | ✅ optional, off by default | — | Always-on, vendor-locked | — |
| Audit trail + REST API | ✅ | Limited to their UI | — | — |
| Cost | Free, run anywhere | Paid tiers | Paid tiers | Free |
How it works
Silent until you tell it what to do.
The bot is completely silent in any repo without an explicit config file — nothing runs by accident.
1
Install the GitHub App
Install it on your org or a single repo. It listens for webhooks, verified with HMAC-SHA256 and constant-time comparison.
2
Add a config file
Drop .github/hiero-bot.yml into the repo. Every workflow section is optional — enable only what you need.
No config file = the bot does nothing, anywhere.
3
Run it anywhere
Python + Postgres/SQLite, or a single Docker container. Your infrastructure, your data.
.github/hiero-bot.yml
repo: "hiero/your-repo"
workflows:
onboarding:
enabled: true
auto_assign_mentor: false
mentor_assignment_strategy: round-robin
pull_request:
enabled: false
reviewer_recommendation: true
ai_review:
enabled: false # requires ANTHROPIC_API_KEY
model: "claude-sonnet-4-20250514"
focus_areas: [security, logic]
quality_gates:
require_tests: true
require_dco: true
min_reviewers: 1
auto_label: true
stale_pr_days: 30
Quickstart
git clone https://github.com/AnthropicBots/hiero-bot-py
cd hiero-bot-py
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload
Docker
docker build -t hiero-bot .
docker run -p 8000:8000 --env-file .env hiero-botUnder the hood
Architecture, API, and commands.
App structure, REST endpoints, and slash commands
app/
├── main.py # FastAPI app + lifespan
├── config/
│ ├── schema.py # Pydantic v2 config schema + validation
│ └── loader.py # YAML loader with TTL cache
├── db/
│ ├── database.py # Async SQLAlchemy engine
│ └── models.py # AuditLog, PRHealthScore, ContributorSnapshot, StaleActionLog, ReviewerRecommendation
├── github/
│ ├── client.py # Async GitHub App HTTP client
│ └── webhooks.py # HMAC-verified webhook router
├── workflows/
│ ├── onboarding.py # First-time contributor flows
│ ├── pullrequest.py # Quality gates + AI review + reviewer rec.
│ ├── prhealth.py # PR health scoring
│ ├── progression.py # Role progression + issue recommendations
│ └── issuemanagement.py # Stale scan + escalation
├── ai/
│ └── reviewer.py # Anthropic SDK integration (pluggable)
├── scheduler/
│ └── jobs.py # APScheduler cron jobs
├── api/
│ └── routes.py # REST API endpoints
└── utils/
└── audit.py, logger.py, settings.py
tests/
├── unit/ # workflow + schema tests
└── integration/ # httpx + in-memory SQLite API testsREST API — /api/v1
| Endpoint | Description |
|---|---|
| GET /health | Service health check |
| GET /audit | Audit log (filter by owner, repo, action, login, since) |
| GET /pr-health | PR health score records |
| GET /pr-health/stats | Aggregate stats for a repo |
| GET /contributors | Contributor snapshots |
| GET /repos/stats | Full repo summary |
| GET /stale-log | Stale action history |
Slash commands
| Command | Who | Description |
|---|---|---|
| /assign | Anyone | Self-assign (eligibility checked) |
| /unassign | Anyone | Remove yourself from an issue |
| /check-eligibility | Contributors | View role progression breakdown |
| /label <name> | Committers+ | Add a label (role-gated) |
| /help | Anyone | Show all commands |
Roadmap
Under active, ongoing development.
Multi-forge support
GitLab, Gitea, and Forgejo, so the same maintainer-ops model works outside GitHub.
Pluggable AI backends
Local and open-weight models as review backends, alongside the existing Anthropic SDK integration.
Portable reputation
Contributor-reputation credentials that travel with a contributor across projects.
Security-hardened 1.0
A hardened, audited release candidate for production maintainer teams.
Hiero Maintainer Bot is currently a solo, unfunded open-source effort, built and maintained alongside full-time study. It's actively seeking grant support to fund the roadmap above as sustained, full-time work rather than nights-and-weekends progress. If you're a maintainer, funder, or organization interested in supporting or piloting this project, open an issue.
Open an issue