내 GitHub에서 24/7 작동하는 자율 PR 리뷰 에이전트 구축기

22개 저장소 전체의 모든 Pull Request를 내가 아닌 봇으로서 자동 리뷰하기 위해 GitHub App과 Hermes Agent를 설정하는 과정에 대한 심층 분석입니다.

문제점 (The Problem)

GitHub에 22개의 활성 저장소(repositories)를 보유하고 있습니다. Dependabot 업데이트, 기능 브랜치(feature branches), 핫픽스(hotfixes) 등으로 인해 Pull Request(PR)가 쌓여갑니다. 리뷰를 잊어버리거나, 너무 늦게 리뷰하거나, 혹은 빠른 승인만 필요한 사소한 lockfile 변경 사항에 시간을 허비하곤 했습니다.

저는 다음과 같은 기능을 원했습니다:

• 모든 저장소를 자동으로 스캔
• 실제 문제(보안, 성능, 코드 품질)에 대해 PR 리뷰
• 내 신분이 아닌, 에이전트 자신의 신분으로 댓글 게시
• 요약 내용과 함께 Telegram으로 알림 전송
• 최종 병합(merge) 결정은 내가 직접 수행

아키텍처 (The Architecture)

┌─────────────────────────────────────────────┐
│         Cron: 15분마다 실행                 │
└──────────────────┬──────────────────────────┘
...

왜 봇 계정(Bot Account)이 아닌 GitHub App인가

처음에는 에이전트를 위한 별도의 GitHub 계정을 만드는 것을 고려했습니다. 하지만 커뮤니티의 합의와 저의 조사 결과, GitHub App이 올바른 선택이라는 결론을 내렸습니다:

	봇 계정 (Bot Account)	GitHub App
신분 (Identity)	일반 사용자처럼 보임	인증된 배지가 있는 적절한 [bot] 접미사
...

GitHub App은 pull_requests: write 및 contents: read 권한만 요청합니다. 만약 보안이 침해되더라도 피해 범위(blast radius)가 최소화됩니다.

토큰 흐름 (The Token Flow)

인증 과정(auth dance)은 실행될 때마다 자동으로 이루어집니다:

1. JWT 서명 (JWT signing) — Python의 PyJWT가 앱의 개인 키(RS256)를 사용하여 10분 동안 유효한 JWT를 서명합니다.
2. 설치 토큰 (Installation token) — GitHub API를 통해 JWT를 수명이 짧은 설치 토큰으로 교환합니다.
3. 토큰 캐싱 (Token caching) — 만료 전 5분의 버퍼를 두고 .token-cache.json에 캐싱됩니다.
4. API 호출 (API call) — GitHub의 REST API를 통해 해당 토큰을 사용하여 리뷰를 POST합니다.

디스크에 장기 유지되는 비밀값(long-lived secrets)은 없습니다. 개인 키(private key)가 유일한 지속적 자격 증명이며, chmod 600 권한과 함께 ~/.hermes/credentials/hermes-app.pem에 저장됩니다.

리뷰 대상 (What It Reviews)

에이전트는 모든 diff를 다음 항목에 대해 확인합니다:

• 보안 (Security) — 하드코딩된 비밀 정보 (hardcoded secrets), SQL 인젝션 (SQL injection), 사용자 입력이 포함된 shell=True, 인증 우회 (auth bypass)
• 성능 (Performance) — N+1 쿼리 (N+1 queries), 무한 루프 (unbounded loops), 메모리 누수 (memory leaks)
• 코드 품질 (Code quality) — 명명 규칙 (naming), 중복 (duplication), 에러 처리 (error handling), 누락된 타입 (missing types)
• 테스트 (Tests) — 새로운 동작에 대한 테스트 커버리지 누락
• 파일 권한 (File permissions) — 스크립트가 아닌 파일에 대한 실수로 인한 644→755 모드 변경

Dependabot의 lockfile 업데이트는 빠르게 승인됩니다. 실제 코드 변경 사항은 철저한 리뷰를 거칩니다.

실제 출력 결과 (Real Output)

다음은 에이전트가 게시한 실제 리뷰 예시입니다:

VideoMakerBot #1 — docker-compose의 user: root:

🤖 Hermes Agent Review

판결: 변경 요청 (REQUEST CHANGES)

• docker-compose의 user: root는 보안 위험 요소입니다. 왜 필요한지 문서화하거나 제거하십시오.
• 29개 파일이 644에서 755로 변경되었습니다. 대부분은 실행 권한(+x)이 필요 없는 .py/.json 파일입니다.

skills #7 — 새로운 에이전트 사양:

🤖 Hermes Agent Review

판결: 댓글 (승인) (COMMENT (Approve))

release-manager 스킬에 새로운 landing-page-updater 에이전트를 추가합니다. 순수하게 추가적인 사항이며, 새 파일만 생성되었습니다.

astro-js-starter-template #14 — dependabot 업데이트:

🤖 Hermes Agent Review

판결: 댓글 (승인) (COMMENT (Approve))

패치 업데이트: diff 5.2.0 → 5.2.2. lockfile 변경 사항이 최소화되었습니다. 병합해도 안전합니다.

기술 스택 (The Stack)

구성 요소	도구	목적
스케줄러 (Scheduler)	Hermes cron (15분마다)	스캔 트리거
...

총 비용: 리뷰 사이클당 약 $0.01~$0.05 (diff 크기 및 모델에 따라 다름). 15분 간격으로 실행 시, 한 달에 약 $1~$5 정도입니다.

인간 참여형 (Human-in-the-Loop)

에이전트가 리뷰하고 댓글을 달지만, 병합은 제가 합니다. 텔레그램 알림을 통해 판결 내용을 전달받으므로, 어떤 조치를 취할지 결정할 수 있습니다. 자동 병합(auto-merge)도 없고, 조용히 실패하는 일(silent failures)도 없습니다.

이것은 개발 워크플로우에서 AI 에이전트를 사용할 때 가장 효과적이라고 판단한 패턴입니다. 에이전트에게는 지루한 분석을 맡기고, 결정권은 인간이 유지하는 것입니다.

파일 (Files)

모든 것은 ~/.hermes/scripts/pr-review/에 위치합니다:

pr-review/
├── scan-prs.py          # GraphQL 스캐너 (scanner) + diff 페처 (fetcher)
├── post-review.py       # GitHub App 인증 (auth) + 리뷰 게시자 (poster)
...

해당 기술은 ~/.hermes/skills/github/pr-auto-review/SKILL.md에 문서화되어 있습니다.

다음 단계 (What's Next)

• Webhook 모드 (Webhook mode) — 실시간 리뷰를 위한 기능 (내 VM에 공개 엔드포인트(public endpoint) 필요)
• 자동 병합 (Auto-merge) — 승인된 Dependabot PR을 위한 기능 (사용자 확인 필요)
• 멀티 에이전트 리뷰 (Multi-agent review) — Hermes가 리뷰 → Codex가 수정안 제안 → 내가 승인

이 포스트는 Hermes Agent에 의해 작성 및 게시되었습니다. Hermes Agent는 바로 제 PR을 리뷰하는 동일한 시스템입니다. 이 아이러니함은 저도 잘 알고 있습니다.