Getting Started

봇 붙이기

우리 리포지토리에서 코드 리뷰 봇을 쓰기까지의 절차다.

리뷰 서버는 관리자가 이미 띄워두었다. 팀이 서버를 따로 준비할 필요는 없고 리포지토리에 파일을 추가하지 않아도 된다. 실제로 해야 하는 일은 설치 요청 하나다.

1. GitHub App을 리포지토리에 설치한다

봇은 GitHub App으로 동작한다. 리포지토리에 App을 설치해야 웹훅이 서버로 간다.

상황	누가 하나
개인 리포지토리	본인이 설치할 수 있다
조직(Organization) 리포지토리	조직 소유자나 리포지토리 admin 권한자
App이 비공개(private)로 등록된 경우	App을 만든 관리자만 설치할 수 있다 → 관리자에게 요청한다

설치 화면에서 Only select repositories 를 골라 리뷰받을 리포지토리만 지정하는 편이 좋다. 나중에 App 설정에서 언제든 추가·제거할 수 있다.

설치할 때 아래 권한을 요구한다. 리뷰를 남기고 설정을 읽는 데 필요한 최소 권한이다.

권한	왜 필요한가
Pull requests — Read & write	리뷰와 인라인 코멘트를 남긴다
Issues — Read & write	👀 리액션, 실패 알림 코멘트를 남긴다
Contents — Read-only	리포지토리의 .reviewbot/config.yml 을 읽는다

2. 관리자에게 허용 목록 등록을 요청한다

서버에는 리뷰를 허용할 리포지토리 목록이 있다. 여기에 없으면 App을 설치해도 웹훅이 무시된다. 모델 사용량이 서버 키 하나에서 나가기 때문에 두는 장치다.

관리자에게 이렇게 요청하면 된다.

코드 리뷰 봇 허용 목록에 owner/repo 추가 부탁드립니다.

owner/repo 는 GitHub 주소에 보이는 그대로 적는다 (예: it-play/Code-Review-Bot). 대소문자까지 정확히 맞아야 한다.

등록이 안 된 상태에서는 PR을 열어도 아무 반응이 없다. 오류 코멘트조차 달리지 않으므로, "아무 일도 안 일어난다"면 이 단계를 먼저 의심한다.

3. 첫 리뷰를 확인한다

설치와 등록이 끝났으면 확인해 본다. 둘 중 아무거나 해도 된다.

• PR을 새로 연다 → 자동으로 리뷰가 돈다
• 기존 PR에 /review 코멘트를 단다 → 그 시점의 변경분을 리뷰한다

/review 는 코멘트의 맨 앞에 와야 한다. 앞에 다른 문장을 붙이면 인식되지 않는다.

/review

정상이라면 몇 초 안에 코멘트에 👀 리액션이 달리고, 몇 분 뒤 리뷰가 올라온다. 모델이 크고 로컬 GPU에서 도는지라 원래 느리다.

반응	뜻
👀	접수했다. 리뷰 중이다
😕	쓰기 권한이 없어 거절했다 → 쓰는 법
아무 반응 없음	허용 목록에 없거나, 명령 형식이 틀렸다 → 문제 해결

여기까지 되면 끝이다. 설정 파일 없이도 계속 쓸 수 있다.

4. (선택) 팀에 맞게 설정한다

기본값이 안 맞을 때만 리포지토리 루트에 .reviewbot/config.yml 을 만든다.

# 사소한 지적은 받지 않는다
minSeverity: major

# 인라인 코멘트는 10개까지만
maxInlineComments: 10

# 이 경로는 리뷰하지 않는다
exclude:
  - 'docs/**'
  - '**/*.generated.ts'

# 우리 팀 규약을 알려준다
customInstructions: |
  - 이 리포지토리는 TypeScript strict 모드다. any 사용을 지적하라.
  - 외부 API 호출에는 반드시 타임아웃과 재시도가 있어야 한다.

설정을 추가한 PR에서 바로 확인할 수 있다. 봇은 PR의 최신 커밋에서 설정을 읽으므로, 머지하기 전에 그 PR에 /review 를 달아 결과를 보면 된다.

전체 항목은 설정에, 상황별 추천 조합은 리뷰 강도 조정에 있다.

gemini-code-assist에서 갈아타기

1. 리포지토리 설정에서 gemini-code-assist App을 제거하거나, .gemini/config.yaml 에서 자동 리뷰를 끈다. 두 봇을 같이 두면 같은 PR에 리뷰가 두 번 달린다
2. 위 1~3단계를 따라 이 봇을 설치한다
3. .gemini/styleguide.md 를 쓰고 있었다면 그 내용을 .reviewbot/config.yml 의 customInstructions 로 옮긴다

명령은 이렇게 대응된다.

gemini-code-assist	이 봇
/gemini review	/review
/gemini summary	(없음)
/gemini 질의	(없음)

리뷰 기능만 있고 요약·질의 명령은 없다.

체크리스트

설치 요청 전에 확인하면 왕복을 줄일 수 있다.

• 리포지토리 admin 권한이 있는가 (없으면 있는 사람에게 요청)
• 관리자에게 전달할 owner/repo 를 정확히 적었는가
• 기존에 다른 코드 리뷰 봇이 붙어 있지 않은가
• 리뷰받고 싶지 않은 경로(생성 코드, 문서)가 있는가 → exclude 준비