<div align="center">
<img src="https://raw.githubusercontent.com/AnthropicBots/hiero-bot-py/HEAD/.github/assets/mark2_orbit_ring.jpg" width="120" height="120" alt="hydra-maintainer logo" />
hydra-maintainer
오픈 소스 유지보서를 위한 자체 호스팅 가능한 오픈 소스 자동화 플랫폼입니다.
PR 건강 점수 측정 · 리뷰어 추천 · 기여자 진행 상황 추적 · 선택적 AI 지원 검토 · 영구 감사 기록(persistent audit trail) · REST API
Python 3.11+
License: MIT
CI
FastAPI
GitHub Marketplace
라이브 대시보드 · 프로젝트 사이트 · 마켓플레이스 목록
</div>
SaaS 종속성 없음(No SaaS lock-in). 사용자의 저장소 데이터를 판매자에게 맡기지 않습니다. 사용자 소유의 봇, 데이터베이스, 규칙을 갖습니다.
문제점 (The problem)
건강한 오픈 소스 프로젝트는 결국 동일한 병목 현상에 직면합니다: 적은 수의 무급 유지보자들이 DCO 서명 확인, 첫 기여자 심사, 오래된 이슈 추적, 누가 커미터가 될 준비가 되었는지 결정하기, 변경되는 파일을 실제로 아는 리뷰어를 추천하는 등의 수동적이고 반복적인 분류 작업을 수행해야 합니다. 이 모든 과정은 어딘가에 문서화되어 있지 않습니다. 유지보자의 머릿속에 존재하다가 그들이 번아웃을 겪으면 사라져 버립니다.
도움을 주기 위해 존재하는 도구들은 두 가지 범주로 나뉩니다:
- 상용 SaaS 봇 (Mergify, CodeRabbit, Greptile 등) — 기능은 뛰어나지만 클로즈드 소스(closed-source)입니다. 사용자의 리포지토리 데이터, 리뷰 기록, 기여자 지표는 다른 사람의 서버에 존재하며, 가격이 변하거나 사라질 수 있는 구독 뒤에 있습니다.
- 단일 목적 OSS 봇 (probot apps, stale-bot, welcome-bot) — 무료이며 자체 호스팅(self-hostable)할 수 있지만, 각각은 하나의 좁은 문제만 해결하며 공유 데이터 모델이 없고, 영구적인 기록이 없으며, 프로젝트가 시간이 지남에 따라 자체 기여자 파이프라인을 추론하는 데 도움이 되는 것이 없습니다.
유지보서 운영(maintainer-ops) 전체를 하나의 시스템으로 다루는 자체 호스팅 오픈 소스 시스템은 아무도 가지고 있지 않습니다. 실제 데이터베이스, 감사 추적(audit trail), 그리고 단지 PR 하나가 게이트를 통과했는지 여부가 아니라 기여자가 프로젝트 내에서 성장하는 방식에 대한 데이터 모델이 필요합니다.
기능 (What it does)
hydra-maintainer는 사용자가 통제하는 인프라 위에서 완전히 실행되는 GitHub App입니다 (FastAPI + SQLAlchemy async + Postgres/SQLite). 이 시스템은 Hiero (Linux Foundation Decentralized Trust) 생태계를 위해 구축되고 테스트되었으며, 단일 리포지토리별 YAML 설정 파일 하나를 통해 모든 GitHub 호스팅 오픈 소스 프로젝트에 일반화 적용이 가능합니다.
| 기능 (Capability) | 설명 (What it does) |
|---|
| 온보딩 (Onboarding) | 첫 기여자를 감지하고, 환영 체크리스트를 게시하며, /assign 전에 계정 연령/공개 리포지토리 개수를 검증하고, 멘토 할당을 순환 방식으로 처리합니다. |
| ... | |
프로젝트의 워크플로우와 REST API를 커버하는 단위 테스트(unit) 및 통합 테스트(pytest-asyncio, httpx, respx, 인메모리 SQLite)가 포함되어 있습니다.
실제 적용 사례 (Seen in the wild)
hydra-maintainer는 실제 풀 리퀘스트(pull requests)에 대해 실시간으로 실행됩니다. 자동으로 게시하는 몇 가지 기능은 다음과 같습니다:
- 어떤 신호가 통과했고 어떤 신호가 통과하지 못했는지 정확하게 분석하고, 무엇을 수정해야 하는지에 대한 쉬운 언어의 힌트를 제공하는 PR 건강 점수표(PR health scorecard).
- 필수 게이트(예: 연결된 종료 이슈)가 충족될 때까지 검토 요청을 차단하는 품질 게이트 보고서(Quality Gate Report).
- 변경된 파일을 마지막으로 수정한 사람을 기반으로 한 리뷰어 제안(Reviewer suggestions)을 강제 검토 요청 대신 가벼운 댓글 형태로 게시.
- 점수와 판정 레이블이 지정된 요약 형태의 AI 코드 리뷰 통과 보고서(AI Code Review)로, 자동화됨으로 명확히 표시되며 항상 인간 검토가 뒤따름.
- 즉각적인 확인 댓글 및 적격성 검사 기능이 포함된
/assign 처리.
차별점 (Why it's different)
| hydra-maintainer | Mergify | CodeRabbit / Greptile | probot / stale-bot / welcome-bot |
|---|
| 라이선스 / 호스팅 | MIT, 자체 호스팅 | 클로즈드 소스 SaaS | 클로즈드 소스 SaaS | 오픈 소스이지만 상태 비저장(stateless) |
| ... | | | | |
아키텍처 (Architecture)
app/
├── main.py # FastAPI 앱 + 생명 주기 관리(lifespan)
├── config/
...
슬래시 명령어 (Slash commands)
| 명령어 | 사용자 | 설명 |
|---|
/assign | 누구나 | 자기 할당 (적격성 확인됨) |
| ... | | |
REST API
기본 경로: /api/v1
| 엔드포인트 | 설명 |
|---|
GET /health | 서비스 상태 점검(Service health check) |
| ... | |
빠른 시작 (Quick start)
git clone https://github.com/AnthropicBots/hiero-bot-py
cd hiero-bot-py
...
Docker
docker build -t hydra-maintainer .
docker run -p 8000:8000 --env-file .env hydra-maintainer
테스트 (Tests)
python -m pytest tests/unit/ tests/integration/ -q
python -m pytest tests/ --cov=app --cov-report=term-missing
보안 감사 (Security audit)
푸시하기 전에, 알려진 취약점에 대해 종속성을 확인하세요:
pip install pip-audit
pip-audit -r requirements.txt -f json -o audit-report.json
python .github/scripts/check_audit_severity.py audit-report.json
CI는 동일한 검사를 실행하고 High/Critical CVSS 발견 시 빌드를 실패시킵니다. pip-audit에는 내장된 심각도 플래그가 없으므로, 위 스크립트에서 각 발견의 CVSS 점수를 기준으로 필터링을 수행합니다.
웹훅 비밀(Webhook secret) 순환 (Rotation)
다운타임 없이 GITHUB_WEBHOOK_SECRET을 순환하려면:
- 새 비밀을
GITHUB_WEBHOOK_SECRET으로, 이전 비밀을 GITHUB_WEBHOOK_SECRET_OLD로 설정합니다.
- 두 비밀이 모두 구성된 상태로 애플리케이션을 배포(Deploy)합니다.
- GitHub App 웹훅 구성을 업데이트하여 새 비밀을 사용하도록 합니다.
- 유예 기간(grace period) 이후,
GITHUB_WEBHOOK_SECRET_OLD를 제거하고 재배포(redeploy)합니다.
순환 기간 동안에는 현재 비밀과 이전 비밀 모두가 허용됩니다.
구성 (Configuration)
애플리케이션이 설치된 모든 리포지토리에 .github/hiero-bot.yml을 추가하세요. 전체 참조: templates/hiero-bot.yml. 설정 파일이 존재하지 않으면 봇은 완전히 침묵합니다—실수로 아무것도 실행되지 않습니다.
기본값. 구성 파일이 존재하는 경우, 온보딩(onboarding), PR 품질 게이트(PR quality gates), PR 건강 점수화(PR health scoring), 기여자 진행 상황(contributor progression)은 enabled: false를 설정하지 않는 한 활성화되어 있습니다. 이슈 관리(stale scan, auto-close, auto-unassign) 및 리뷰어 할당은 비활성화되어 있으며, 예를 들어 workflows.issue_management.enabled: true와 같이 명시적으로 활성화해야 합니다.
환경 변수 (Environment variables)
| 변수 | 필수 여부 | 설명 |
|---|
GITHUB_APP_ID | ✅ | GitHub App 설정에서 가져옴 |
| ... | | |
대시보드와 보호된 REST API 엔드포인트는 서명되고 데이터베이스 백업이 된 세션(signed, database-backed sessions)을 사용하는 GitHub OAuth를 사용합니다. 애플리케이션을 공개적으로 노출하기 전에 GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET, SESSION_SECRET_KEY, 및 TOKEN_ENCRYPTION_KEY를 구성하세요. | | |
생태계 및 현황 (Ecosystem & standing)
원래 Linux Foundation Decentralized Trust 하의 Hiero 생태계에 있는 저장소들을 대상으로 구축 및 검증되었습니다. 저자는 hiero-sdk-python 및 기타 Hiero 관련 프로젝트의 활동적인 기여자이며, ECWoC'26 Top Contributor입니다. 설정 형식은 의도적으로 범용적(모든 소유자/저장소, 모든 팀 이름)이어서, 수정 없이 비(非)Hiero, GitHub 호스팅 FOSS 프로젝트에도 동일한 봇을 설치할 수 있습니다.
로드맵
이 프로젝트는 활발하게 개발이 진행 중입니다. 계획된 작업에는 멀티 포지(multi-forge) 지원(GitLab/Gitea/Forgejo), 플러그인 가능한 로컬/오픈 웨이트 AI 검토 백엔드, 휴대용 기여자 평판 자격 증명, 그리고 보안 강화된 1.0 버전 출시가 포함됩니다.
자금 지원 및 지원
hydra-maintainer는 현재 풀타임 학업과 병행하여 구축되고 유지되는 개인적이고 비(非)자금 지원 오픈 소스 노력입니다. 이 프로젝트가 밤샘 또는 주말 진행이 아닌 지속적인 풀타임 작업으로 로드맵을 구현할 수 있도록 지원하는 그랜트 자금을 적극적으로 모색하고 있습니다. 만약 관리자, 기여자, 또는 이 프로젝트를 지원하거나 파일럿 운영하는 데 관심 있는 조직이라면, 이슈를 열거나 아래 링크를 통해 연락해 주십시오.
기여하기
이슈와 PR을 환영합니다. 커밋에 서명(DCO)하고 새로운 워크플로우 로직에 대한 테스트를 포함해 주십시오. 새 패턴을 추가하기 전에 기존 패턴은 tests/unit/에서 확인하십시오.
작성자
Mohit Yadav (@mohityadav8) — CS 학부생 (BE-CSE, Chandigarh University, 2024–2028), NVIDIA/aicr, SHAP, pgmpy, hiero-sdk-python, OWASP Nest 등 다양한 오픈 소스 기여자. 포트폴리오: mohityadav8.github.io
라이선스
MIT License — LICENSE 참조.
