PR-Agent 로컬 환경 설정 및 테스트

김가희·2025년 5월 3일

PR-Agent 로컬 환경 실행법

1. LLM API key 발급

PR-Agent는 PR 자동 요약, 리뷰, 개선 제안을 수행하기 위해 LLM API를 필요로 한다.
공식 문서에서는 OpenAI를 기본값으로 설명하고 있지만, HuggingFace, Azure OpenAI, Google Gemini 등 다양한 LLM 공급자 중에서 선택할 수 있다. 나는 비용 측면을 고려하여 Gemini를 선택하였다.

🔹 발급 방법

Google AI Studio 사이트에 접속한다.
구글 계정으로 로그인한다.
Dashboard-API Keys 탭에 들어가서 API 키 만들기 버튼을 누른다.
생성된 키를 복사해서 별도로 저장해 둔다.

2. Git 플랫폼 Token 발급

PR-Agent가 PR의 내용을 읽고 분석하기 위해서는 Git 플랫폼에 접근할 수 있는 권한이 필요하다. 이를 위해 각 플랫폼에 맞는 API Token 또는 Access Token을 발급받아야 한다.
PR-Agent는 GitHub, GitLab, Bitbucket 등 다양한 Git 플랫폼을 지원한다. 이 글에서는 GitHub을 기준으로 발급 방법을 소개하겠다.

🔹 발급 방법

GitHub Personal Access Tokens (fine-grained) 페이지에 접속한다.
Generate new token 버튼을 클릭한다.
New fine-grained personal access token 생성 과정에서 중요한 설정은 다음 두 가지다.

PR-Agent를 사용할 레포지토리 지정
필요한 퍼미션 부여

나의 경우에는 아래와 같이 설정했다.

Contents → Read and write (review, improve 명령어를 사용해 PR의 코드 파일을 수정하거나 설명을 추가할 수 있도록 허용)

Pull requests → Read and write (PR 본문을 읽고 자동 설명 추가, 코드 리뷰 코멘트 작성, 코드 제안 커밋, approve 처리 등 자동 리뷰 작업 수행)

Issues, Metadata → Read-only (PR에 연결된 이슈를 참조하거나, 레포지토리의 기본 정보(브랜치, 팀 등)를 읽어들이기 위해 사용)

생성된 토큰을 복사하여 별도로 저장해 둔다. 이 토큰은 한 번만 표시된다.

🔹 권한 미설정 시 403 오류 발생

토큰에 적절한 권한이 부여되지 않으면, PR-Agent 사용 시 다음과 같은 403 오류가 발생할 수 있다.

403 오류

2025-05-02 14:52:20.906 | ERROR    | pr_agent.tools.pr_reviewer:run:177 - Failed to review PR: 403 {"message": "Resource not accessible by personal access token", "documentation_url": "https://docs.github.com/rest/issues/comments#create-an-issue-comment", "status": "403"}

3. 가상 환경 설치

PR-Agent는 Python 기반의 CLI 도구로, 독립된 가상 환경에서 실행하는 것이 권장된다. 가상 환경을 사용하는 이유는 프로젝트별로 필요한 패키지 버전을 분리해 충돌을 방지하고, 의존성을 명확히 관리할 수 있기 때문이다.

IDE로 PR-Agent를 사용할 프로젝트를 열고, 가상 환경을 실행한다.

PR-Agent 레포지토리 클론 및 이동
git clone https://github.com/레포지토리주소/프로젝트이름.git
cd pr-agent

Python 가상 환경 생성 및 활성화
python3 -m venv venv
source venv/bin/activate  (Linux/macOS 기준)
source venv/Scripts/activate  (Windows 기준)

which python3을 입력했을 때 이미지처럼 경로가 뜨면 정상적으로 실행된 것이다.

4. PR-Agent 설치

가상 환경이 활성화된 상태에서 PR-Agent를 설치한다. 이는 로컬 프로젝트에 필요한 패키지를 전역이 아닌 가상 환경 내부에만 설치하기 위해서이며, 다른 프로젝트들과의 충돌을 방지할 수 있다.

패키지 설치
pip install -e .

-e 옵션은 editable mode로 설치하겠다는 의미로, 로컬에서 코드 변경 시 바로 적용되도록 도와준다.

5. 설정

PR-Agent는 두 개의 설정 파일을 통해 동작한다.

.secrets.toml → API 키, 사용자 토큰 등 민감한 정보를 담는 파일
configuration.toml → 기본 모델, Fallback 모델 등 PR-Agent의 전반적인 설정을 관리하는 파일

🔹 .secrets.toml 설정

# secrets 템플릿 파일 복사 및 권한 설정
cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml
chmod 600 pr_agent/settings/.secrets.toml

.secrets.toml 파일에 chmod 600 권한을 설정하는 이유는, 파일의 소유자에게만 읽기/쓰기 권한을 부여함으로써 토큰이나 API 키 같은 민감한 정보가 외부에 노출되는 보안 이슈를 예방하기 위함이다.

복사한 .secrets.toml 파일을 열어 다음과 같이 수정한다.

[google_ai_studio]
gemini_api_key = "<your-gemini-api-key>"  # 사용할 LLM API 키

[github]
user_token = "<your-github-token>"        # GitHub Personal Access Token

🔹 configuration.toml 설정

AI 모델과 백업용 모델을 지정하기 위해 configuration.toml 설정 파일을 열어 사용할 AI 모델을 지정한다.

[config]
model="gemini/gemini-1.5-flash"           # 기본 모델 설정
fallback_models = ["gemini-1.5-flash"]    # 실패 시 대체 모델 목록

사용 가능한 모델 목록은 pr_agent/algo/init.py 파일에서 확인할 수 있다.

6. 실행

아래와 같이 터미널에 명령어를 입력하여 PR-Agent를 실행할 수 있다.
예시 명령어 중 하나를 실행하면, 해당 PR에 대한 자동 리뷰 결과를 GitHub 코멘트로 확인할 수 있다.

# <command>: PR-Agent가 제공하는 주요 명령어
python3 -m pr_agent.cli --pr_url <pr_url> review           # PR 코드 리뷰
python3 -m pr_agent.cli --pr_url <pr_url> describe         # PR 요약 설명
python3 -m pr_agent.cli --pr_url <pr_url> improve          # 코드 개선 제안
python3 -m pr_agent.cli --pr_url <pr_url> add_docs         # 문서화 보완
python3 -m pr_agent.cli --pr_url <pr_url> generate_labels  # 라벨 자동 생성
python3 -m pr_agent.cli --pr_url <pr_url> ask "<질문>"     # 자유 질문
python3 -m pr_agent.cli --issue_url <issue_url> similar_issue  # 유사 이슈 추천