AI 코드 리뷰 도우미

AI 코드 리뷰 도우미

LLM 기반의 자동화된 코드 리뷰 도우미입니다. GitHub/GitLab Webhook을 통해 PR/MR 변경 사항을 모니터링하고, AI를 활용해 코드를 분석한 후 리뷰 의견을 PR/MR에 자동으로 코멘트로 추가합니다. 다양한 알림 채널도 지원합니다.

Bilibili 데모 영상 보기

GitHub 제한으로 인해 비디오 플레이어를 직접 삽입할 수 없습니다.

주요 기능

다중 플랫폼 지원: GitHub 및 GitLab Webhook 통합, Pull Request / Merge Request 이벤트 모니터링.
지능형 리뷰 모드:
- 상세 리뷰 (/github_webhook, /gitlab_webhook): AI가 각 변경 파일을 분석하여 구체적인 문제점을 찾습니다. 리뷰 의견은 구조화된 형태(예: 특정 코드 라인 위치, 문제 분류, 심각도, 분석 및 제안)로 PR/MR에 개별 코멘트로 추가됩니다. AI 모델은 JSON 형식의 분석 결과를 출력하며, 시스템은 이를 여러 개의 독립적인 코멘트로 변환합니다.
- 일반 리뷰 (/github_webhook_general, /gitlab_webhook_general): AI가 각 변경 파일에 대한 전체적인 분석을 수행하고, 각 파일에 대해 Markdown 형식의 요약 코멘트를 생성합니다.
자동화 프로세스:
- AI 리뷰 의견(상세 모드에서는 여러 개, 일반 모드에서는 파일당 하나)을 PR/MR에 자동 게시.
- 모든 파일 리뷰 완료 후 PR/MR에 요약 코멘트 자동 게시.
- AI가 보고할 만한 문제를 찾지 못한 경우에도 친절한 안내 메시지와 요약 코멘트 게시.
- 비동기식 리뷰 작업 처리로 Webhook에 빠르게 응답.
- Redis를 통해 동일한 Commit에 대한 중복 리뷰 방지.
유연한 구성:
- 환경 변수를 통해 기본 설정 구성.
- 웹 관리 패널(/admin) 및 API(/config/*) 제공:
  - GitHub/GitLab 저장소/프로젝트의 Webhook Secret 및 Access Token 관리.
  - LLM 매개변수(API Key, Base URL, Model) 관리.
  - 알림 Webhook URL(기업 WeChat, 사용자 정의 Webhook) 설정.
  - AI 리뷰 기록 조회.
- Redis를 사용한 구성 및 리뷰 결과의 영구적 저장.
알림 및 기록:
- 리뷰 요약(PR/MR 링크, 브랜치 정보, 리뷰 결과 개요 포함)을 기업 WeChat 및 사용자 정의 Webhook으로 전송.
- Redis에 리뷰 결과 저장(기본 7일 만료), 관리 패널에서 조회 가능하며, 닫히거나 병합된 PR/MR의 기록은 자동 정리.
배포: Docker 배포 또는 Python 애플리케이션 직접 실행 지원.

🚀 빠른 시작

🐳 빠른 배포 시작

# 使用官方镜像
docker run -d -p 8088:8088 \
  -e ADMIN_API_KEY="your-key" \
  -e OPENAI_API_BASE_URL="https://api.openai.com/v1" \
  -e OPENAI_API_KEY="your-key" \
  -e OPENAI_MODEL="gpt-4o" \
  -e REDIS_HOST="your-redis-host" \
  -e REDIS_PASSWORD="your-redis-pwd"
  --name ai-code-review-helper \
  dingyufei/ai-code-review-helper:latest

📌 필수 환경 변수:

ADMIN_API_KEY - 관리자 백엔드 비밀번호 기본값: change_this_unified_secret_key

OPENAI_API_KEY - AI 서비스 키

REDIS_HOST - Redis 주소

구성

1. 환경 변수 (일부 주요)

ADMIN_API_KEY: 필수. 관리 인터페이스를 보호하는 비밀키, 기본값은 change_this_unified_secret_key이며 반드시 변경해야 합니다.
OPENAI_API_KEY: 필수. OpenAI API 키.
OPENAI_MODEL: (기본값: gpt-4o) 사용할 OpenAI 모델.
OPENAI_API_BASE_URL: (선택 사항) OpenAI API 기본 URL, 형식: http(s)://xxxx/v1 기본값: https://api.openai.com/v1
WECOM_BOT_WEBHOOK_URL: (선택 사항) 기업 WeChat 봇 Webhook URL.
REDIS_HOST: 필수. Redis 서버 주소. 구성되지 않거나 연결할 수 없는 경우 서비스가 시작되지 않습니다.
REDIS_PORT: (기본값: 6379) Redis 서버 포트.
REDIS_PASSWORD: (선택 사항) Redis 비밀번호.
REDIS_DB: (기본값: 0) Redis 데이터베이스 번호.
REDIS_SSL_ENABLED: (기본값: true) Redis 연결에 SSL 사용 여부. false로 설정하여 SSL을 비활성화할 수 있습니다.
(기타 변수 SERVER_HOST, SERVER_PORT, GITHUB_API_URL, GITLAB_INSTANCE_URL 등은 시작 로그 또는 소스 코드 참조.)

2. 관리 패널 및 API

관리 패널 (/admin): 웹 인터페이스 제공:
- GitHub 저장소 및 GitLab 프로젝트의 Webhook Secret 및 Access Token 구성.
- 전역 LLM 매개변수(OpenAI API Key, Base URL, Model) 관리.
- 전역 알림 Webhook URL(기업 WeChat 봇, 사용자 정의 Webhook) 설정.
- AI 리뷰 기록 조회 및 관리.
- 모든 관리 작업은 환경 변수 ADMIN_API_KEY로 설정된 비밀키로 인증이 필요합니다.
구성 API: RESTful API(/config/*) 제공, 프로그래밍 방식으로 위 구성을 관리할 수 있으며, X-Admin-API-Key 요청 헤더로 인증이 필요합니다.

구성 지속성:

Redis (필수): 저장소/프로젝트 구성, 처리된 Commit SHA, AI 리뷰 결과 저장(기본 7일 만료, 닫히거나 병합된 PR/MR의 관련 기록 자동 정리). 서비스는 Redis에 강력하게 의존합니다.
환경 변수: 주로 전역 구성(LLM Key/URL, Redis 연결 정보, Admin API Key 등) 로드에 사용됩니다. 관리 패널을 통해 이러한 전역 구성을 수정하면 런타임에 즉시 적용되지만, 서비스 재시작 시 환경 변수에서 다시 로드됩니다. 따라서 지속성이 필요한 전역 구성은 환경 변수를 통해 관리하는 것이 좋습니다.

사용 방법

서비스 시작: Docker 사용 또는 Python 애플리케이션 직접 실행, 필수 환경 변수(ADMIN_API_KEY, OPENAI_API_KEY, REDIS_HOST 등) 구성 확인.
저장소/프로젝트 구성: 관리 패널(/admin) 또는 API를 통해 대상 GitHub 저장소 또는 GitLab 프로젝트 구성 추가, Webhook Secret 및 PR/MR 코멘트 읽기/쓰기 권한이 있는 Access Token 포함.
Webhook 설정: GitHub/GitLab 저장소/프로젝트 설정에서 Webhook 추가:
- Payload URL: 서비스 주소 및 해당 Webhook 엔드포인트(아래 참조)를 가리킵니다.
- Content type: application/json.
- Secret: 관리 패널에서 구성한 Webhook Secret 입력.
- Events: GitHub는 "Pull requests" 선택, GitLab은 "Merge request events" 체크.
리뷰 트리거: PR/MR 생성 또는 업데이트 시 서비스가 자동으로 코드 리뷰를 수행합니다.

리뷰 모드 선택

상세 리뷰 (엔드포인트: /github_webhook, /gitlab_webhook):
- AI는 각 파일의 변경 사항을 세밀하게 분석하여 구체적인 코드 라인(가능한 경우)에 대한 구조화된 리뷰 의견을 생성합니다.
- 각 문제는 PR/MR의 해당 코드 라인(가능한 경우) 또는 전체 코멘트의 일부로 개별 게시됩니다.
- 이 모드에서 AI 모델은 JSON 형식의 분석 결과를 출력하도록 지시받으며, 시스템은 이를 파싱하여 PR/MR의 코멘트로 변환합니다.
- 지시 사항을 잘 따르고 안정적인 JSON을 출력할 수 있는 모델(예: GPT-4 시리즈)에 적합합니다. 코멘트가 이상하거나 누락된 경우 애플리케이션 로그에서 LLM의 원시 출력이 예상된 JSON 형식과 일치하는지 확인하세요.
일반 리뷰 (엔드포인트: /github_webhook_general, /gitlab_webhook_general):
- AI는 각 변경 파일의 전체 내용을 분석하고 해당 파일에 대한 단일 Markdown 형식의 리뷰 코멘트를 생성합니다.
- 이 모드는 파일 변경 사항에 대한 거시적 평가가 필요하거나 상세 리뷰 모드의 모델 출력이 불안정할 때 적합합니다.

개발 모드

# 1. 克隆仓库
git clone https://github.com/dingyufei615/ai-code-review-helper.git
cd ai-code-review-helper

# 2. 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置环境变量 (参考 .env.example 或 配置 部分)

# 5. 启动服务
python -m api.ai_code_review_helper

# 6. 运行测试 (可选)
python -m unittest discover tests

주의 사항

보안: 강력한 ADMIN_API_KEY를 사용하고 모든 Token 및 Secret을 안전하게 보관하세요.
비용: 사용하는 LLM 서비스의 API 호출 비용에 유의하세요.
로그: 서비스는 문제 해결을 위해 상세한 실행 로그를 콘솔에 출력합니다.
Redis 의존성: 서비스는 구성 및 결과 저장을 위해 Redis에 강력하게 의존합니다.

기여

이 코드의 90%는 Aider + Gemini 협업으로 완성되었습니다. Pull Request 또는 Issue 제출을 환영합니다.