깃허브 AI 코드리뷰 자동화 도입기 (PR_AGENT, GEMENI & 무료 🫜)

프로젝트가 커질수록 PR 리뷰의 일관성을 유지하는 것은 쉽지 않다.

리뷰어마다 템플릿을 다르게 쓰거나, 라벨링을 빼먹거나, 검토자를 일일이 지정해야 하는 일은 반복된다.
이때, AI의 시대를 살아가는 우리는 코드리뷰에 AI를 도입하면 어떨까, 생각하게 되는데.
찾던도중 무료로 사용할 수 있으면서 쉽게 적용할 수 있는 걸 찾아보았다.
 

그리고 발견한 도구가 바로 pr_agent다.
 

pr_agent란 무엇인가 👑

pr_agent는 GitHub Actions에서 동작하는 자동화 봇으로, PR 생성/수정 시 다음과 같은 작업을 자동으로 수행한다.
(직접 로컬에 받아서 사용할 수도 있는데, 깃헙 액션이 간단하기에 요거로 설정하기로 했다)

• PR 본문에 팀 표준 템플릿 삽입
• 커밋 내용 기반 라벨 추가
• 코드 영역/작성자에 맞는 리뷰어 추천
• PR 체크리스트 자동 주입

즉, PR의 형식과 메타데이터를 자동화하여 리뷰 품질을 일정하게 유지하도록 돕는 도구라고 보면 된다.
AI 기반으로 코드 변경 요약, 리뷰 포인트 제안 등의 기능도 추가적으로 지원한다고 한다.
 

설치 및 기본 설정

1. pr_agent 설치

프로젝트 루트에 GitHub Actions 워크플로를 추가한다.

# .github/workflows/pr_agent.yml
name: PR Agent
on:
  pull_request:
    types: [opened, edited, synchronize]

jobs:
  pr_agent:
    runs-on: ubuntu-latest
    steps:
      - uses: Codium-ai/pr-agent@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

 
그런데, 기본으로 설정되어 있는 openAI 모델은 유료이다... (chatGPT와는 요금 정책이 다른 듯)
https://platform.openai.com/api-keys
 
그래서, 무료로 할 수 있는 방법을 찾아보았고 이 글을 발견했다.
 
제미나이로 설정해본 결과 잘 작동했고, 설정은 다음과 같다 !

name: PR Agent (Gemini)
on:
  pull_request:
    types: [opened, reopened, ready_for_review, synchronize]
  issue_comment:
jobs:
  pr_agent_job:
    if: ${{ github.event.sender.type != 'Bot' }}
    runs-on: ubuntu-latest
    permissions:
      issues: write
      pull-requests: write
      contents: write
    steps:
      - name: PR Agent action step
        uses: qodo-ai/pr-agent@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          config.model: 'gemini/gemini-2.5-flash'
          config.fallback_models: '["gemini/gemini-2.5-flash"]'
          GOOGLE_AI_STUDIO.GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          config.response_language: 'ko-KR'
          github_action_config.auto_review: 'true'
          github_action_config.auto_describe: 'true'
          github_action_config.auto_improve: 'true'
          github_action_config.pr_actions: '["opened", "reopened", "ready_for_review", "synchronize"]'

위와 같이 설정해주자.
깃헙 토큰은 자동으로 설정되므로 제미나이 키만 잘 넣어주면 된다.
GEMENI_API_KEY는 깃헙 레포지토리에 시크릿에 추가해주고, 키는 구글 ai studio에서 발급받을 수 있다.
https://aistudio.google.com/app/api-keys?hl=ko

로그인 - Google 계정

 

2. 설정 파일 추가

프로젝트 루트에 .pr_agent.toml 파일을 생성하고, 아래와 같이 템플릿과 규칙을 정의한다.
(여기저기서 구글링해서 찾은 내용으로 설정해봤다)

[general]
language = "ko"
enable_summary = true
enable_reviewer_suggestion = true

[templates]
default = """
## 📋 PR 요약
변경된 내용에 대한 간략한 설명을 작성해주세요.

## ✅ 체크리스트
- [ ] 코드가 정상적으로 빌드되는지 확인하셨나요?
- [ ] 테스트가 모두 통과했나요?
- [ ] 문서(README 등)가 최신 상태인가요?

## 💬 리뷰어 참고사항
"""

[labels]
docs = ["README", "docs"]
feature = ["feat"]
fix = ["fix", "bug"]

 

로컬 훅과의 역할 분리

husky나 lint-staged와 같은 로컬 훅은 개발자 개인의 커밋 전 점검용으로 두고, pr_agent는 서버에서 PR 메타데이터를 다루는 역할로 분리하는 것이 안전하다.
이렇게 하면 충돌 없이 CI 파이프라인과 함께 안정적으로 작동시킬 수 있다.
 

실무 예제 🫡 실제 팀 적용 흐름

1. 로컬 개발
   • 커밋 전 husky + lint-staged로 린트 검사
   • 커밋 메시지는 Conventional Commits 규약 준수
2. PR 생성
   • pr_agent가 자동으로 템플릿 주입, 라벨링, 리뷰어 추천
3. CI 실행
   • 테스트 및 빌드 자동 검증
4. 리뷰 및 머지
   • 리뷰어는 체크리스트 기반으로 효율적 검토
5. 모니터링
   • 필요 시 .pr_agent.toml 수정으로 자동화 수준 조정

 

터미널에서 테스트하기

pr_agent는 실제 PR을 열지 않아도 로컬에서 테스트할 수 있다.
GitHub 웹훅 시뮬레이터를 이용하거나, CI 환경에서 테스트 브랜치로 PR을 생성해 로그를 확인할 수도 있다고 한다.
 

실무에서의 팁

• 훅 충돌 주의 -> PR 본문 자동 수정 시 로컬 훅에서 본문을 다시 검사하지 않도록 분리
• 민감 정보 금지 -> 템플릿에 API 키나 토큰 같은 민감 정보는 절대 포함하지 않기
• 점진적 적용 -> 모든 PR에 바로 적용하지 말고, 특정 라벨(예: feature/*)에만 먼저 시범 적용하기
• 문서화 -> README 또는 CONTRIBUTING.md에 pr_agent 규칙을 명시하여 팀 전체가 규칙을 인지하게 하기

 

실제 코드리뷰 자동화 효과는 ??

• PR 본문이 통일되어 리뷰어 간 커뮤니케이션 효율 상승
• 라벨·검토자 지정 자동화로 리뷰 사이클 단축
• 체크리스트 기반 QA·릴리즈 품질 관리 가능

결국 pr_agent는 “자동화된 리뷰 가이드”로서,
코드 품질을 관리하면서도 리뷰 피로도를 줄여주는 실무형 도구라 할 수 있다.
(리뷰도 공수가 많이 들어가는 일이다...)
 
실제 사용해보면, 요렇게 나오는데 다이어그램도 작성해준다 🤩 (https://github.com/citron03/practice-next-15/pull/4)

참고 자료

• Codium AI - pr_agent 공식 문서
• How to AI Code Review for Free (dev.to)
• GitHub Actions Docs - Workflow syntax