GitHub Pull Request 검토를 위한 오픈 소스 AI 앱, baloo-bear

Baloo는 AI 풀 리퀘스트(pull request) 검토를 위한 오픈 소스 GitHub App입니다. 이 앱은 사용자의 저장소에 설치되어 PR의 차이점(diffs)과 관련 프로젝트 컨텍스트를 읽고, 사람이 코드를 검토하기 전에 버그, 보안 문제, 누락된 오류 처리, 그리고 저장소 가이드라인 위반을 포착하는 실행 가능한 검토 댓글을 게시합니다.

Baloo는 호스팅되는 SaaS 리뷰어 대신 자체 호스팅(self-hosted) AI 코드 검토 에이전트를 원하는 팀을 위해 구축되었습니다. 사용자가 서비스를 직접 운영하고, GitHub App 설치 범위를 제어하며, Claude 또는 Gemini와 같은 모델의 API 키를 직접 제공할 수 있습니다.

웹사이트: BlueBear Security

린터(linter)가 잡아낼 수 없는 것 포착 — 논리 오류, 조용한 실패(silent failures), 보안 안티패턴, 누락된 오류 처리
사용자 컨벤션 존중 — 저장소의 AGENTS.md 및 CONTRIBUTING.md 파일을 읽고 이를 강제 적용합니다.
PR별 검토 지침 준수 — PR에 ## Review guidance for Baloo가 포함된 경우, Baloo는 이러한 반증 가능한(falsifiable), 컨텍스트 인식 체크를 검증하고 발견 사항에 인용합니다.
팀원처럼 게시 — 특정 라인에 대한 인라인 댓글, 심각도 레이블, 승인/변경 요청 결정을 내립니다.
모든 푸시(push) 시 실행 — 새로운 커밋이 자동으로 검토되며, 반복 과정 전반의 토론 스레드를 추적합니다.
자체 호스팅 및 비공개 — 코드가 사용자의 인프라를 벗어나지 않습니다. 자체 API 키를 가져오세요.

GitHub 풀 리퀘스트용 AI 코드 검토 — 열리거나, 다시 열리거나, 동기화되거나, 검토 준비가 된 PR을 검토합니다.
보안 검토 지원 — 주입 위험(injection risks), 안전하지 않은 인증 패턴(unsafe auth patterns), 비밀 처리 실수, 누락된 유효성 검사를 플래그 지정합니다.
저장소 가이드라인 강제 적용 — AGENTS.md 및 CONTRIBUTING.md에서 프로젝트별 규칙을 적용합니다.

종속성 업데이트 검토 — 종속성 PR에 대해 Dependabot 인식 프롬프트를 사용합니다.
계획 충실도 확인 — 승인 전에 구현 사항을 계획 문서와 비교합니다.
PR 생성 전 로컬 검토 — 동일한 검토 파이프라인을 로컬 git diff에 실행할 수 있습니다.

PR이 열리거나 업데이트될 때, Baloo가 검토를 게시합니다:

🐻 Baloo 검토 완료: 45초 소요.
발견된 이슈: 2개 (Critical 0, High 1, Medium 1, Low 0).

인라인 코멘트는 정확한 줄에 표시됩니다:

[HIGH] 보안—src/auth.py:55
SQL 쿼리가 매개변수 바인딩 대신 문자열 연결을 사용합니다. 이는 SQL 인젝션에 취약합니다.

권장 사항: 매개변수화된 쿼리 사용:cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

Webhook URL: 공개 HTTPS 엔드포인트 (예: https://baloo.example.com/webhook)

)
권한(Permissions): Pull requests (읽기/쓰기), Contents (읽기), Checks (읽기/쓰기)
이벤트(Events): Pull request, Check run, Check suite (후자 두 개가 Re-run 버튼을 구동함) - 개인 키 다운로드
.pem

파일

git clone https://github.com/Blue-Bear-Security/baloo-bear.git
cd baloo-bear
cp .env.example .env
...

docker compose up --build

사용자 저장소에 GitHub App을 설치하세요. PR을 열면 Baloo가 자동으로 검토합니다.

📖 전체 설정 가이드: docs/getting-started.md

📖 더 정교한 리뷰 받기: docs/how-to-get-the-most.md — 컨벤션, PR별 리뷰 브리프, 그리고 Baloo를 문맥 인식(context-aware) 검토자로 변신시키는 워크플로우

┌──────────────┐ webhook ┌───────────────────┐
│ GitHub │ ───────────────→ │ FastAPI │
│ (PR 이벤트) │ │ webhook_handler │
...

baloo/
├── agent/ # PI runtime, 프롬프트, 구조화된 출력 파싱
├── config/ # 설정 (환경 변수 + DB 런타임 오버레이)
...

설정은 환경 변수를 통해 구성되며, DATABASE_ENABLED=true일 때 허용 목록에 포함된 에이전트 노브(agent knobs)도 런타임 시 재정의될 수 있습니다.
. 주요 변수:

전체 참고 자료: docs/configuration.md

📖 전체 문서 — 기능 가이드, 구성 참조 및 기타

기능 가이드:

– Baloo를 최대한 활용하는 방법 — 컨벤션, PR 검토 브리프, 고신호도 워크플로우
– 리뷰 에이전트 — 에이전틱(agentic) 리뷰 작동 방식
– 가이드라인 강제 적용 — 레포지토리 컨벤션 확인
– 충실도 분석 — 계획 대 구현 점수화
– 문서 드리프트 — PR 시점의 오래된 문서 감지
– 모델 — 지원되는 제공업체, 모델 및 티어
– 심각도 라우팅 — 발견 사항이 개발자에게 도달하는 방식
– 토론 추적 — 반복(iteration) 전반에 걸친 스레드 후속 조치
– FP 검증 — 거짓 양성(False-positive) 감소
– 대시보드 — 리뷰 기록 UI

uv sync && npm install # 의존성 설치
uv run python main.py # 로컬 실행
uv run pytest # 테스트
...

Python 종속성을 변경할 때는 커밋하기 전에 해시 고정(hash-pinned) 프로덕션 요구사항을 재생성하세요:

uv export --frozen --no-dev --no-emit-project --no-header --output-file requirements-prod.txt

CI는 이 파일을 uv export와 비교하고,
Docker 이미지는 여기서 프로덕션 종속성을 설치합니다.

PR을 열기 전에 작업 중인 트리(working tree)에 대해 동일한 리뷰 파이프라인을 실행할 수 있습니다. 스크립트는 git diff(base...head)로부터 합성 PR을 빌드하고, 존재할 경우 head ref에서 AGENTS.md 또는 CONTRIBUTING.md를 로드하며, 발견 사항을 stdout에 출력합니다 — GitHub에는 아무것도 게시되지 않습니다.

프로덕션과 동일한 LLM 자격 증명(예: 환경 변수에 있는 ANTHROPIC_API_KEY 또는 GEMINI_API_KEY)이 필요합니다.

uv run python scripts/local_review.py
uv run python scripts/local_review.py --base origin/main --head HEAD
uv run python scripts/local_review.py --json
...

전체 기여자 가이드는 docs/development.md를 참조하세요.

네. Baloo는 자체 서비스이자 GitHub App으로 실행됩니다. 배포, 레포지토리 설치 범위, 데이터베이스 지속성 및 모델 자격 증명은 사용자가 제어합니다.

아니요. Baloo는 Baloo가 호스팅하는 백엔드를 필요로 하지 않습니다. 실행되는 서비스는 사용자의 GitHub App 설치를 통해 레포지토리 콘텐츠를 읽고 구성한 LLM 제공업체에 리뷰 컨텍스트를 전송합니다.

Baloo는 Anthropic, Amazon Bedrock, Google, OpenAI, 그리고 Databricks AI Gateway 제공업체를 지원합니다. 선택된 제공업체는 모든 에이전트에 적용됩니다. 자세한 내용은 docs/features/models.md 및 docs/features/databricks.md를 참조하세요.

아니요. Baloo는 정적 분석을 보완하는 검토(review) 에이전트입니다. 알려진 패턴에 대해서는 결정론적 스캐너를 유지하고, 추론(reasoning)-중심의 발견 사항, 프로젝트 컨벤션, 그리고 PR 수준의 검토 맥락에는 Baloo를 사용하세요.

예. scripts/local_review.py를 사용하여 로컬 git diff에 대한 건식(dry) 검토를 실행할 수 있습니다.

이슈 및 버그 보고: GitHub Issues기능 요청: GitHub Issues질문: GitHub Discussion을 열거나 이슈를 제출하세요

기여는 환영합니다! 워크플로우와 컨벤션은 CONTRIBUTING.md를, AI 에이전트별 지침은 AGENTS.md를 참고하세요.

취약점을 보고하기 전에 SECURITY.md를 읽어보세요.

MIT — LICENSE 참조.