PR-Agent 기본 설정 및 사용법 분석

Tasker_Jang·2025년 4월 29일
agent오픈소스인공지능
0

PR-Agent는 AI를 활용하여 Pull Request를 효율적으로 관리하고 리뷰하기 위한 도구입니다. 이 도구는 PR 설명 자동 생성, 코드 리뷰, 개선 제안, 질문 응답 등 다양한 기능을 제공합니다. 이 글에서는 PR-Agent의 설치 방법, 기본 설정, 그리고 실제 사용 방법에 대해 상세히 알아보겠습니다.

1. PR-Agent 개요

PR-Agent는 AI 기반 PR 리뷰 도구로, 다음과 같은 주요 기능을 제공합니다:

  • PR 설명 생성 (/describe): PR의 제목, 유형, 요약, 코드 설명, 라벨 등을 자동으로 생성
  • PR 리뷰 (/review): PR에 대한 피드백, 잠재적 문제, 보안 문제, 리뷰 노력 등을 제공
  • 코드 개선 제안 (/improve): PR 코드 개선을 위한 제안 제공
  • 질문 응답 (/ask): PR에 대한 자유로운 질문에 답변
  • CHANGELOG 업데이트 (/update_changelog): PR 변경 사항으로 CHANGELOG.md 파일 자동 업데이트
  • 문서 지원 (/help_docs): 주어진 문서를 활용하여 저장소에 대한 질문에 답변

PR-Agent는 GitHub, GitLab, Bitbucket, Azure DevOps 등 다양한 Git 제공자를 지원하며, CLI, GitHub Actions, 웹훅, 앱 등 다양한 방식으로 사용할 수 있습니다.

2. 설치 방법

PR-Agent를 사용하기 위한 여러 가지 설치 방법이 있습니다:

2.1 Docker를 사용한 설치

Docker 이미지를 사용하면 쉽게 PR-Agent를 실행할 수 있습니다:

# GitHub
docker run --rm -it -e OPENAI.KEY=<your key> -e GITHUB.USER_TOKEN=<your token> codiumai/pr-agent:latest --pr_url <pr_url> review

# GitLab
docker run --rm -it -e OPENAI.KEY=<your key> -e CONFIG.GIT_PROVIDER=gitlab -e GITLAB.PERSONAL_ACCESS_TOKEN=<your token> codiumai/pr-agent:latest --pr_url <pr_url> review

# BitBucket
docker run --rm -it -e CONFIG.GIT_PROVIDER=bitbucket -e OPENAI.KEY=$OPENAI_API_KEY -e BITBUCKET.BEARER_TOKEN=$BITBUCKET_BEARER_TOKEN codiumai/pr-agent:latest --pr_url=<pr_url> review

2.2 pip 패키지 설치

pip를 통해 PR-Agent를 패키지로 설치할 수 있습니다:

pip install pr-agent

설치 후 다음과 같은 스크립트로 실행할 수 있습니다:

from pr_agent import cli
from pr_agent.config_loader import get_settings

def main():
    # 필요한 값 입력
    provider = "github" # github/gitlab/bitbucket/azure_devops
    user_token = "..."  # 사용자 토큰
    openai_key = "..."  # OpenAI 키
    pr_url = "..."      # PR URL, 예: 'https://github.com/Codium-ai/pr-agent/pull/809'
    command = "/review" # 실행할 명령어 ('/review', '/describe', '/ask="질문"', ...)

    # 설정하기
    get_settings().set("CONFIG.git_provider", provider)
    get_settings().set("openai.key", openai_key)
    get_settings().set("github.user_token", user_token)

    # 명령어 실행 (피드백은 GitHub PR 댓글에 표시됨)
    cli.run_command(pr_url, command)

if __name__ == '__main__':
    main()

2.3 소스코드에서 실행

소스코드에서 직접 실행하는 방법:

  1. 저장소 클론:

    git clone https://github.com/Codium-ai/pr-agent.git

  2. 의존성 설치:

    cd pr-agent
pip install -e .

  3. 시크릿 설정 파일 생성:

    cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml
chmod 600 pr_agent/settings/.secrets.toml
# .secrets.toml 파일 편집

  4. CLI 스크립트 실행:

    python3 -m pr_agent.cli --pr_url <pr_url> review
python3 -m pr_agent.cli --pr_url <pr_url> ask <your question>
python3 -m pr_agent.cli --pr_url <pr_url> describe
python3 -m pr_agent.cli --pr_url <pr_url> improve

2.4 GitHub Action으로 설치

GitHub Action으로 PR-Agent를 설치하려면:

  1. 다음 파일을 저장소에 .github/workflows/pr_agent.yml로 추가:
on:
  pull_request:
    types: [opened, reopened, ready_for_review]
  issue_comment:
jobs:
  pr_agent_job:
    if: ${{ github.event.sender.type != 'Bot' }}
    runs-on: ubuntu-latest
    permissions:
      issues: write
      pull-requests: write
      contents: write
    name: Run pr agent on every pull request, respond to user comments
    steps:
      - name: PR Agent action step
        id: pragent
        uses: qodo-ai/pr-agent@main
        env:
          OPENAI_KEY: ${{ secrets.OPENAI_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  1. GitHub 저장소에 OPENAI_KEY 시크릿 추가
  2. 변경사항을 main 브랜치에 병합

3. configuration.toml 상세 분석

PR-Agent의 핵심 설정 파일인 configuration.toml은 도구의 모든 동작을 제어합니다. 중요한 설정 항목을 살펴보겠습니다:

3.1 기본 설정 (config 섹션)

[config]
# 모델 설정
model="o4-mini"
fallback_models=["gpt-4.1"]
#model_reasoning="o4-mini" # 자가 반성을 위한 전용 추론 모델
#model_weak="gpt-4o" # 더 간단한 작업을 위한 약한 모델(선택 사항)

# CLI 설정
git_provider="github"
publish_output=true
publish_output_progress=true
verbosity_level=0 # 0,1,2
use_extra_bad_extensions=false

# 로그 설정
log_level="DEBUG"

# 구성 설정
use_wiki_settings_file=true
use_repo_settings_file=true
use_global_settings_file=true
disable_auto_feedback = false
ai_timeout=120 # 2분
skip_keys = []
custom_reasoning_model = false # true일 때 채팅 스타일 입력을 지원하지 않는 모델을 위해 시스템 메시지 및 온도 제어를 비활성화
response_language="en-US" # ISO 3166 및 ISO 639 형식의 PR 응답 언어 로케일 코드 (예: "en-US", "it-IT", "zh-CN", ...)

# 토큰 제한
max_description_tokens = 500
max_commits_tokens = 500
max_model_tokens = 32000 # 모델의 기본 기능에 관계없이 모델에서 사용할 수 있는 최대 토큰 수를 제한
custom_model_max_tokens=-1 # 기본 목록에 없는 모델용
model_token_count_estimate_factor=0.3 # 토큰 수 추정치를 늘리는 요소, 토큰이 너무 많아 모델이 실패할 가능성을 줄이기 위함

# 패치 확장 로직
patch_extension_skip_types =[".md",".txt"]
allow_dynamic_context=true
max_extra_lines_before_dynamic_context = 10 # 패치의 각 청크 전에 최대 10줄까지 추가 라인 포함 (함수나 클래스를 둘러싸는 부분까지)
patch_extra_lines_before = 5 # 패치의 각 청크 전에 추가 라인 수 (+3 기본 라인)
patch_extra_lines_after = 1 # 패치의 각 청크 후에 추가 라인 수 (+3 기본 라인)

이 섹션은 PR-Agent의 기본 동작을 정의합니다. 사용할 AI 모델, 출력 설정, 토큰 제한, 패치 처리 방법 등을 설정할 수 있습니다.

3.2 PR 리뷰 도구 설정 (pr_reviewer 섹션)

[pr_reviewer] # /review #
# 기능 활성화/비활성화
require_score_review=false
require_tests_review=true
require_estimate_effort_to_review=true
require_can_be_split_review=false
require_security_review=true
require_ticket_analysis_review=true
# 일반 옵션
persistent_comment=true
extra_instructions = ""
final_update_message = true
# 리뷰 라벨
enable_review_labels_security=true
enable_review_labels_effort=true
# 증분 리뷰를 위한 특정 구성 (/review -i)
require_all_thresholds_for_incremental_review=false
minimal_commits_for_incremental_review=0
minimal_minutes_for_incremental_review=0
enable_intro_text=true
enable_help_text=false # PR 리뷰에 도움말 텍스트를 포함할지 여부 (기본값: 활성화)

이 섹션은 PR 리뷰 도구의 동작을 설정합니다. 어떤 유형의 분석을 수행할지, 리뷰 결과를 어떻게 표시할지 등을 정의합니다.

3.3 PR 설명 도구 설정 (pr_description 섹션)

[pr_description] # /describe #
publish_labels=false
add_original_user_description=true
generate_ai_title=false
use_bullet_points=true
extra_instructions = ""
enable_pr_type=true
final_update_message = true
enable_help_text=false
enable_help_comment=true
# 댓글로 설명 게시
publish_description_as_comment=false
publish_description_as_comment_persistent=true
## 변경 사항 안내 섹션
enable_semantic_files_types=true
collapsible_file_list='adaptive' # true, false, 'adaptive'
collapsible_file_list_threshold=6
inline_file_summary=false # false, true, 'table'
# 마커
use_description_markers=false
include_generated_by_header=true
# 대규모 PR 모드 💎
enable_large_pr_handling=true
max_ai_calls=4
async_ai_calls=true

PR 설명 생성 도구를 구성하는 부분입니다. 자동 생성된 라벨 발행 여부, 원본 사용자 설명 추가 여부, 제목 생성 여부 등을 설정할 수 있습니다.

3.4 코드 제안 도구 설정 (pr_code_suggestions 섹션)

[pr_code_suggestions] # /improve #
max_context_tokens=24000
#
commitable_code_suggestions = false
dual_publishing_score_threshold=-1 # -1은 비활성화, [0-10]은 코드 제안을 표와 커밋 가능한 형태로 모두 게시하기 위한 임계값(>=)
focus_only_on_problems=true
#
extra_instructions = ""
enable_help_text=false
enable_chat_text=false
persistent_comment=true
max_history_len=4
publish_output_no_suggestions=true
# 제안 적용 활성화 💎
apply_suggestions_checkbox=true
# 제안 점수 매기기
suggestions_score_threshold=0 # [0-10]| 8 이상으로 설정하지 않는 것이 좋음, 관련성이 높은 제안이 잘릴 수 있음
new_score_mechanism=true
new_score_mechanism_th_high=9
new_score_mechanism_th_medium=7
# '/improve --extended' 모드의 매개변수
auto_extended_mode=true
num_code_suggestions_per_chunk=4
max_number_of_calls = 3
parallel_calls = true

코드 개선 제안 도구의 설정입니다. 최대 컨텍스트 크기, 제안 점수 임계값, 커밋 가능한 제안 여부 등을 설정할 수 있습니다.

3.5 자동화 설정

PR-Agent는 다양한 자동화 기능을 제공합니다:

GitHub App 자동화 설정:

[github_app]
# GitHub 앱 배포를 위한 설정
bot_user = "github-actions[bot]"
override_deployment_type = true
# "pull_request" 이벤트 설정
handle_pr_actions = ['opened', 'reopened', 'ready_for_review']
pr_commands = [
    "/describe --pr_description.final_update_message=false",
    "/review",
    "/improve",
]
# "pull_request" 이벤트와 "synchronize" 액션을 위한 설정 - 새 커밋을 위한 푸시 트리거를 감지하고 처리하는 데 사용
handle_push_trigger = false
push_trigger_ignore_bot_commits = true
push_trigger_ignore_merge_commits = true
push_trigger_wait_for_initial_review = true
push_trigger_pending_tasks_backlog = true
push_trigger_pending_tasks_ttl = 300
push_commands = [
    "/describe",
    "/review",
]

이 섹션은 GitHub 앱이 PR에 자동으로 응답하는 방식을 정의합니다. 새 PR이 열리거나 업데이트될 때 실행할 명령어를 지정할 수 있습니다.

GitLab 웹훅 자동화 설정:

[gitlab]
url = "https://gitlab.com"
pr_commands = [
    "/describe --pr_description.final_update_message=false",
    "/review",
    "/improve",
]
handle_push_trigger = false
push_commands = [
    "/describe",
    "/review",
]

GitLab에서의 자동화 설정입니다. PR(MR)이 열리거나 업데이트될 때 실행할 명령어를 지정합니다.

4. 실제 사용 방법

PR-Agent를 실제로 사용하는 방법은 크게 두 가지로 나눌 수 있습니다:

4.1 로컬 저장소 (CLI) 사용

로컬 환경에서 PR-Agent를 CLI로 사용하는 방법:

# 리뷰 실행
python -m pr_agent.cli --pr_url=<pr_url> review

# 설명 생성
python -m pr_agent.cli --pr_url=<pr_url> describe

# 코드 개선 제안
python -m pr_agent.cli --pr_url=<pr_url> improve

# 질문 응답
python -m pr_agent.cli --pr_url=<pr_url> ask "이 PR에 대한 시나 팝송을 작성해줘"

# CHANGELOG 업데이트
python -m pr_agent.cli --pr_url=<pr_url> update_changelog

명령줄 매개변수를 통해 설정을 변경할 수도 있습니다:

python -m pr_agent.cli --pr_url=<pr_url> /review --pr_reviewer.extra_instructions="파일에 집중: ..."

4.2 온라인 사용 (PR 댓글)

GitHub, GitLab, Bitbucket 등의 플랫폼에서 PR 댓글을 통해 PR-Agent를 사용하는 방법:

  • 리뷰 실행: /review
  • 설명 생성: /describe
  • 코드 개선 제안: /improve (Bitbucket에서는 /improve_code)
  • 질문 응답: /ask "..."
  • CHANGELOG 업데이트: /update_changelog

댓글에서도 설정을 변경할 수 있습니다:

/review --pr_reviewer.extra_instructions="..." --pr_reviewer.require_score_review=false

4.3 자동화 설정

PR이 열리거나 업데이트될 때 PR-Agent가 자동으로 실행되도록 설정할 수 있습니다:

  • GitHub App: github_app.pr_commands 및 github_app.push_commands 설정 사용
  • GitHub Action: GitHub 워크플로 파일에서 환경 변수를 통해 설정
  • GitLab Webhook: gitlab.pr_commands 및 gitlab.push_commands 설정 사용
  • BitBucket App: bitbucket_app.pr_commands 설정 사용

자동 피드백을 완전히 비활성화하려면:

[config]
disable_auto_feedback = true

5. 특징 및 장점

PR-Agent의 주요 특징과 장점:

  1. 실제 사용 중심: 각 도구는 단일 LLM 호출로 작동하여 약 30초 내에 빠르고 경제적으로 결과를 제공합니다.
  2. PR 압축 전략: 효과적인 압축 전략을 통해 짧은 PR과 긴 PR 모두 효과적으로 처리할 수 있습니다.
  3. 모듈식, 맞춤형 도구: JSON 프롬프팅 전략을 통해 모듈식이고 맞춤화 가능한 도구를 제공합니다.
  4. 다중 지원: 여러 Git 제공자(GitHub, GitLab, Bitbucket), 다양한 사용 방법(CLI, GitHub Action, GitHub App, Docker 등), 여러 모델(GPT, Claude, Deepseek 등)을 지원합니다.

6. 결론

PR-Agent는 AI를 활용하여 PR 관리와 리뷰 프로세스를 효율화하는 강력한 도구입니다. 설치가 간단하고 사용법이 직관적이며, 다양한 Git 제공자와 사용 방법을 지원합니다. configuration.toml 파일을 통해 다양한 측면을 사용자 정의할 수 있어 팀과 프로젝트의 요구에 맞게 조정할 수 있습니다.

PR 설명 자동 생성, 체계적인 코드 리뷰, 코드 개선 제안, 질문 응답 등의 기능을 통해 개발자와 리뷰어의 시간을 절약하고 PR 품질을 향상시킬 수 있습니다. GitHub Action이나 웹훅을 통한 자동화 기능은 워크플로우를 더욱 원활하게 만들어줍니다.

PR-Agent를 도입하면 개발 팀은 더 효율적인 코드 리뷰 프로세스를 구축하고, 더 나은 코드 품질을 유지하면서 개발 속도를 높일 수 있을 것입니다.

profile
Tasker_Jang
ML Engineer 🧠 | AI 모델 개발과 최적화 경험을 기록하며 성장하는 개발자 🚀 The light that burns twice as bright burns half as long ✨
이전 포스트

Agent2Agent(A2A) 프로토콜: AI 에이전트 간 협업을 위한 구글의 오픈 표준

다음 포스트

PR-Agent Describe 기능 분석

0개의 댓글