설치 가이드

1. 계정 신청: etudes0803@gmail.com 로 팀 이름·이메일·저장소를 보내 주시면 계정을 열고 api_key 를 회신합니다(공개 가입은 아직 열지 않았습니다)
2. POST /api/repos 로 저장소 등록 → webhook_secret 수령(이것도 1회만 노출).
   GitHub 토큰은 fine-grained PAT — Repository access 는 그 저장소만, Permissions 는 Pull requests: Read(파일·커밋 목록) + Issues: Read and write(요약 댓글). Metadata: Read 는 자동 포함. 등록할 때 토큰이 저장소와 PR 목록을 읽을 수 있는지 확인합니다.

   curl -X POST https://<host>/api/repos -H "X-Api-Key: prb_..." -H "Content-Type: application/json" \
     -d '{"full_name":"owner/repo","github_token":"github_pat_..."}'

3. GitHub repo → Settings → Webhooks → Add webhook
   Payload URL https://<host>/webhooks/github, Content type application/json, Secret은 발급받은 webhook_secret, 이벤트는 Pull requests만
4. PR 을 열면 봇 댓글. 아래 조회는 모두 헤더 X-Api-Key: prb_... 가 필요합니다: 사용량 GET /api/usage, 처리 기록 GET /api/events?status=failed, PR 요약 GET /api/pull-requests/{owner}/{repo}/{번호}

안 될 때

• 댓글이 안 달림: curl "https://<host>/api/events?status=failed" -H "X-Api-Key: prb_..." 의 error 를 봅니다. 토큰 문제면 PATCH /api/repos/{repo_id} 로 새 토큰을 넣고 PR 에 다시 push 하면 처리됩니다. 실패한 이벤트 재처리는 운영자만 할 수 있으니 필요하면 문의해 주세요.
• 이벤트가 skipped: quota exceeded 면 이번 기간 사용량을 다 쓴 것(이용권은 그 30일, Free 는 매월 1일 UTC 초기화), repository not registered 면 그 저장소가 등록돼 있지 않은 것입니다.
• "임시 요약" 댓글: 모델 호출이 실패해 규칙 기반 요약이 나간 것입니다. 이벤트는 completed, PR 요약의 summary_status 는 fallback 입니다. 연결 실패 등은 같은 커밋의 다음 이벤트(PR 수정·push)에서 다시 시도하고 사용량에 세지 않습니다. 모델이 응답했는데 결과 형식이 깨진 경우는 1건으로 세고, 다음 push 때 새로 요약합니다.
• GitHub 에 401: 웹훅 Secret 이 등록 때 받은 webhook_secret 과 다릅니다.