Almagest ReviewerDashboard →

Documentation

Almagest Reviewer

Almagest Reviewer는 Pull Request 코드 리뷰를 자동화하기 위해 설계된 GitHub App입니다. LangGraph를 사용해 리뷰 과정을 명시적인 상태 전이(State Transition), 루프(loop), 그리고 인간 개입 지점(human-in-the-loop)으로 구성합니다.

단순한 LLM 호출이나 규칙 기반 분석을 넘어, 코드 리뷰를 에이전트의 사고 흐름(process)으로 모델링하는 것을 목표로 합니다.

LangGraph

Agentic workflow

Multi-LLM

Anthropic · Gemini · Ollama

GitHub App

Webhook 기반 실시간 리뷰

Getting Started

Prerequisites

  • Python 3.11 이상
  • Docker & Docker Compose
  • GitHub App 생성 권한
  • Anthropic API Key 또는 Google API Key (Ollama 사용 시 불필요)

Installation

레포지토리를 클론하고 환경변수 파일을 생성합니다.

git clone https://github.com/okdoittttt/almagest-reviewer.git
cd almagest-reviewer

cp .env.example .env

.env 파일을 열어 아래 항목들을 채웁니다.

변수설명
GITHUB_APP_ID생성한 GitHub App의 ID
GITHUB_PRIVATE_KEY_PATH다운로드한 .pem 키 파일 경로
GITHUB_WEBHOOK_SECRETGitHub App에 설정한 Webhook Secret
LLM_PROVIDERanthropic / google / ollama 중 하나
ANTHROPIC_API_KEYAnthropic 사용 시 필요
GOOGLE_API_KEYGoogle Gemini 사용 시 필요
OLLAMA_BASE_URLOllama 서버 주소 (기본값: http://localhost:11434)
GITHUB_CLIENT_IDGitHub App OAuth 클라이언트 ID
GITHUB_CLIENT_SECRETGitHub App OAuth 클라이언트 Secret
ALLOWED_GITHUB_USERS대시보드 접근을 허용할 GitHub 로그인명 (콤마 구분)
JWT_SECRET세션 토큰 서명에 사용할 임의의 랜덤 문자열
ℹ

DATABASE_URL은 Docker Compose 환경에서 자동으로 설정됩니다. 로컬 실행 시에는 .env에서 직접 지정하세요.

Running the Server

deploy.sh를 사용하면 이미지 빌드, 마이그레이션, 컨테이너 기동을 한 번에 처리합니다.

chmod +x deploy.sh
./deploy.sh deploy   # 빌드 → 마이그레이션 → 기동
명령어설명
./deploy.sh deploy이미지 빌드 → 마이그레이션 → 전체 기동
./deploy.sh up컨테이너 기동 (빌드 없음)
./deploy.sh down컨테이너 종료
./deploy.sh migrate마이그레이션만 실행 (alembic upgrade head)
./deploy.sh status마이그레이션 버전 및 미적용 항목 확인
./deploy.sh logs앱 로그 확인 (예: ./deploy.sh logs db)

기동 후 접근 가능한 주소:

  • http://localhost:8000 — API 서버 + 웹 대시보드
  • http://localhost:5173 — 프론트엔드 개발 서버 (hot-reload)
ℹ

GitHub App 설정의 Callback URL에 http://localhost:8000/api/auth/callback이 등록되어 있어야 웹 대시보드 로그인이 동작합니다.

Key Features

Agentic Code Review

코드 분석 → 이슈 분류 → 리뷰 생성 과정을 LangGraph 그래프로 모델링합니다. 단순 체인이 아닌 상태 기반 에이전트 플로우로 체계적인 리뷰를 제공합니다.

Multi-LLM Provider

Anthropic Claude, Google Gemini, Ollama(로컬)를 지원합니다. LLM_PROVIDER 환경변수 하나로 전환할 수 있습니다.

Intelligent Risk Assessment

PR의 의도와 변경 규모를 분석해 위험도(LOW / MEDIUM / HIGH)를 자동으로 분류합니다. LOW로 판단된 PR은 상세 파일 리뷰를 건너뛰어 빠르게 처리합니다.

GitHub App Integration

Pull Request 이벤트 기반으로 실시간 리뷰 코멘트를 작성합니다. 앱이 설치된 모든 레포지토리에서 자동으로 동작합니다.

Web Dashboard

GitHub OAuth 로그인 기반 관리 UI를 제공합니다. 연동된 저장소, PR 리뷰 결과, 스킬 설정을 브라우저에서 확인하고 관리할 수 있습니다.

Multi-repo Support

여러 레포지토리에 앱을 설치하고 레포별 설정을 독립적으로 관리합니다. 웹훅 payload에서 installation_id를 동적으로 추출하므로 서버 수정 없이 연동이 완료됩니다.

Architecture

리뷰 프로세스는 4단계 그래프 노드로 구성됩니다. 위험도에 따라 일부 단계는 건너뜁니다.

01

Intent Analysis

PR 제목과 설명을 분석해 기능 추가 · 버그 수정 · 리팩토링 등의 의도를 파악합니다.

02

Risk Classification

변경 규모와 중요도를 바탕으로 위험도(LOW / MEDIUM / HIGH)를 평가합니다. LOW이면 파일 리뷰를 건너뜁니다.

03

File Review (병렬)

MEDIUM / HIGH PR의 변경 파일을 병렬로 동시 리뷰합니다. 코드 품질, 보안, 성능, 가독성을 검토합니다.

04

Review Summary

모든 분석을 종합해 최종 의견(APPROVE / REQUEST_CHANGES / COMMENT)과 요약문을 작성합니다. 리뷰가 불충분하면 파일 리뷰를 최대 2회 재실행합니다.

Multi-repo Integration

웹훅 payload에서 installation_id를 동적으로 추출하므로, 서버 코드 수정 없이 GitHub App 설치만으로 모든 레포지토리 연동이 완료됩니다.

Step 1. GitHub App 추가 설치

GitHub → Settings → Applications → almagest-reviewer 옆 Configure 클릭 후 Repository access에서 연동할 레포지토리를 추가합니다.

Step 2. 자동 등록 확인

설치된 레포지토리에서 PR을 하나 열면 repositories 테이블에 자동 등록됩니다. 직접 확인하려면:

docker exec -it almagest-reviewer-db-1 psql -U almagest -d almagest_reviewer \
  -c "SELECT id, owner, name, installation_id, is_active FROM repositories ORDER BY created_at DESC;"

리뷰 일시 중단

연동은 유지하되 리뷰를 멈추려면 is_active를 false로 변경합니다.

UPDATE repositories
SET is_active = false
WHERE owner = 'my-org' AND name = 'my-repo';

Self-hosted Deployment

레포지토리를 fork해 자신만의 서버를 운영하는 절차입니다.

Step 1

레포지토리 Fork

GitHub에서 이 레포지토리를 fork합니다.

Step 2

GitHub App 신규 등록

GitHub → Settings → Developer settings → GitHub Apps → New GitHub App에서 앱을 생성합니다.

항목값
Webhook URLhttps://your-domain.com/webhook
Webhook secret임의의 비밀 문자열
Repository permissionsPull requests: Read & write
Subscribe to eventsPull request
Step 3

환경변수 설정 및 서버 배포

cp .env.example .env
# .env 편집 후

docker compose up -d --build
Step 4

GitHub App 설치

생성한 GitHub App 페이지 → Install App → 리뷰를 받을 레포지토리 선택.

Troubleshooting

401 Unauthorized (Webhook)

GITHUB_APP_ID 또는 Private Key 경로가 올바른지 확인하세요.

Invalid Webhook Signature

GITHUB_WEBHOOK_SECRET이 GitHub App 설정의 값과 일치하는지 확인하세요.

LLM API Errors

API Key가 유효한지, 할당량이 남아있는지 확인하세요.

로그인 후 403

ALLOWED_GITHUB_USERS에 본인의 GitHub 로그인명이 포함되어 있는지 확인하세요.

로그인 콜백 오류

GitHub App Settings의 Callback URL에 http://localhost:8000/api/auth/callback이 등록되어 있는지 확인하세요.