튜토리얼: GitHub PR 리뷰 에이전트 구축
문제: 팀이 검토할 수 있는 속도보다 더 빠르게 PR이 열립니다. PR은 며칠 동안 리뷰를 기다리고, 아무도 확인할 시간이 없어 주니어 개발자가 버그를 머지하기도 합니다. 아침에는 기능을 만드는 대신 diff를 따라잡는 데 시간을 씁니다.
해결책: 저장소를 24시간 감시하면서 새 PR을 버그, 보안 문제, 코드 품질 관점에서 검토하고 요약을 보내는 AI 에이전트입니다. 덕분에 실제로 사람의 판단이 필요한 PR에만 시간을 쓸 수 있습니다.
이 튜토리얼에서 만들 것:
┌───────────────────────────────────────────────────────────────────┐
│ │
│ Cron Timer ──▶ Hermes Agent ──▶ GitHub API ──▶ Review │
│ (every 2h) + gh CLI (PR diffs) delivery │
│ + skill (Telegram, │
│ + memory Discord, │
│ local) │
│ │
└───────────────────────────────────────────────────────────────────┘
이 가이드에서는 cron 작업으로 일정에 따라 PR을 폴링합니다. 서버나 공개 엔드포인트가 필요하지 않으며, NAT와 방화벽 뒤에서도 작동합니다.
사용 가능한 공개 엔드포인트가 있다면 웹훅을 사용한 자동 GitHub PR 댓글을 확인하세요. PR이 열리거나 업데이트될 때 GitHub가 Hermes에 이벤트를 즉시 푸시합니다.
전제 조건
- Hermes Agent 설치 - 설치 가이드를 참조하세요.
- cron 작업을 위한 게이트웨이 실행:
hermes gateway install # Install as a service
# or
hermes gateway # Run in foreground - GitHub CLI(
gh) 설치 및 인증:# Install
brew install gh # macOS
sudo apt install gh # Ubuntu/Debian
# Authenticate
gh auth login - 메시징 구성(선택 사항) - Telegram 또는 Discord
deliver: "local"을 사용하면 리뷰를 ~/.hermes/cron/output/에 저장할 수 있습니다. 알림을 연결하기 전에 테스트하기 좋습니다.
1단계: 설정 확인
Hermes가 GitHub에 접근할 수 있는지 확인합니다. 채팅을 시작하세요.
hermes
간단한 명령으로 테스트합니다.
Run: gh pr list --repo NousResearch/hermes-agent --state open --limit 3
열린 공개 PR 목록이 표시되어야 합니다. 여기까지 작동하면 준비가 된 것입니다.
2단계: 직접 검토 시도
같은 채팅에서 Hermes에게 실제 PR을 검토해 달라고 요청합니다.
Review this pull request. Read the diff, check for bugs, security issues,
and code quality. Be specific about line numbers and quote problematic code.
Run: gh pr diff 3888 --repo NousResearch/hermes-agent
Hermes는 다음을 수행합니다.
gh pr diff을 실행하여 코드 변경 사항을 가져옵니다.- 전체 diff를 읽습니다.
- 구체적인 발견 사항을 포함한 구조화된 리뷰를 작성합니다.
품질에 만족한다면 자동화할 차례입니다.
3단계: 리뷰 스킬 생성
스킬은 세션과 cron 실행 전반에서 Hermes가 일관된 리뷰 지침을 따르도록 해 줍니다. 스킬이 없으면 실행마다 리뷰 품질이 달라질 수 있습니다.
mkdir -p ~/.hermes/skills/code-review
~/.hermes/skills/code-review/SKILL.md를 생성합니다.
---
name: code-review
description: Review pull requests for bugs, security issues, and code quality
---
# Code Review Guidelines
When reviewing a pull request:
## What to Check
1. **Bugs** — Logic errors, off-by-one, null/undefined handling
2. **Security** — Injection, auth bypass, secrets in code, SSRF
3. **Performance** — N+1 queries, unbounded loops, memory leaks
4. **Style** — Naming conventions, dead code, missing error handling
5. **Tests** — Are changes tested? Do tests cover edge cases?
## Output Format
For each finding:
- **File:Line** — exact location
- **Severity** — Critical / Warning / Suggestion
- **What's wrong** — one sentence
- **Fix** — how to fix it
## Rules
- Be specific. Quote the problematic code.
- Don't flag style nitpicks unless they affect readability.
- If the PR looks good, say so. Don't invent problems.
- End with: APPROVE / REQUEST_CHANGES / COMMENT
로드되었는지 확인합니다. hermes를 시작했을 때 시작 시 표시되는 스킬 목록에 code-review가 보이면 됩니다.
4단계: 팀 규칙 가르치기
이 단계가 리뷰어를 실제로 유용하게 만듭니다. 세션을 시작하고 Hermes에게 팀의 표준을 알려 주세요.
Remember: In our backend repo, we use Python with FastAPI.
All endpoints must have type annotations and Pydantic models.
We don't allow raw SQL — only SQLAlchemy ORM.
Test files go in tests/ and must use pytest fixtures.
Remember: In our frontend repo, we use TypeScript with React.
No `any` types allowed. All components must have props interfaces.
We use React Query for data fetching, never useEffect for API calls.
이 기억은 계속 유지됩니다. 이후 리뷰어는 매번 다시 설명하지 않아도 해당 규칙을 적용합니다.
5단계: 자동화된 cron 작업 생성
이제 모든 조각을 연결합니다. 2시간마다 실행되는 cron 작업을 만듭니다.
hermes cron create "0 */2 * * *" \
"Check for new open PRs and review them.
Repos to monitor:
- myorg/backend-api
- myorg/frontend-app
Steps:
1. Run: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
2. For each PR created or updated in the last 4 hours:
- Run: gh pr diff NUMBER --repo REPO
- Review the diff using the code-review guidelines
3. Format output as:
## PR Reviews — today
### [repo] #[number]: [title]
**Author:** [name] | **Verdict:** APPROVE/REQUEST_CHANGES/COMMENT
[findings]
If no new PRs found, say: No new PRs to review." \
--name "pr-review" \
--deliver telegram \
--skill code-review
예약되었는지 확인합니다.
hermes cron list
기타 유용한 일정
| 일정 | 언제 |
|---|---|
0 */2 * * * | 2시간마다 |
0 9,13,17 * * 1-5 | 하루 3회, 평일에만 |
0 9 * * 1 | 매주 월요일 아침 정리 |
30m | 30분마다(트래픽이 많은 저장소) |
6단계: 온디맨드 실행
일정을 기다리고 싶지 않다면 수동으로 트리거할 수 있습니다.
hermes cron run pr-review
또는 채팅 세션 내에서:
/cron run pr-review
더 나아가기
GitHub에 직접 리뷰 게시
Telegram으로 전달하는 대신 에이전트가 PR 자체에 코멘트를 남기도록 할 수 있습니다.
cron 프롬프트에 다음을 추가하세요.
After reviewing, post your review:
- For issues: gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW"
- For critical issues: gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW"
- For clean PRs: gh pr review NUMBER --repo REPO --approve --body "Looks good"
gh에 repo 범위의 토큰이 있는지 확인하세요. 리뷰는 gh가 인증된 사용자 이름으로 게시됩니다.
주간 PR 대시보드
모든 저장소에 대한 월요일 아침 요약을 만듭니다.
hermes cron create "0 9 * * 1" \
"Generate a weekly PR dashboard:
- myorg/backend-api
- myorg/frontend-app
- myorg/infra
For each repo show:
1. Open PR count and oldest PR age
2. PRs merged this week
3. Stale PRs (older than 5 days)
4. PRs with no reviewer assigned
Format as a clean summary." \
--name "weekly-dashboard" \
--deliver telegram
다중 저장소 모니터링
프롬프트에 더 많은 저장소를 추가해 확장하세요. 에이전트는 저장소를 순차적으로 처리하므로 추가 설정이 필요하지 않습니다.
문제 해결
"gh: 명령을 찾을 수 없습니다"
게이트웨이는 최소한의 환경에서 실행됩니다. gh가 시스템 PATH에 있는지 확인하고 게이트웨이를 다시 시작하세요.
리뷰가 너무 일반적입니다
code-review스킬 추가(3단계)- Hermes에게 메모리를 통해 팀 규칙을 가르치세요(4단계)
- 스택에 대한 컨텍스트가 많을수록 리뷰가 더 좋아집니다.
cron 작업이 실행되지 않습니다
hermes gateway status # Is the gateway running?
hermes cron list # Is the job enabled?
레이트 리밋
GitHub는 인증된 사용자에게 시간당 5,000개의 API 요청을 허용합니다. 각 PR 리뷰에는 약 3~5개의 요청(목록 + diff + 선택적 댓글)이 사용됩니다. 하루에 100개의 PR을 리뷰해도 한도 안에 들어옵니다.
다음 단계
- 웹훅 기반 PR 리뷰 - PR이 열릴 때 즉시 리뷰를 받습니다(공개 엔드포인트 필요).
- Daily Briefing Bot - PR 리뷰와 아침 뉴스 다이제스트를 결합합니다.
- 플러그인 빌드 - 리뷰 로직을 공유 가능한 플러그인으로 래핑합니다.
- 프로필 - 자체 메모리와 구성을 사용하는 전용 리뷰어 프로필을 실행합니다.
- 대체 제공자 - 한 제공자가 다운되어도 리뷰가 계속 실행되도록 보장합니다.