reviewdog로 코드 리뷰 자동화 구축하기

코드 품질 관리에서 반복적인 수동 검토는 개발자의 생산성을 저하시키는 주요 원인이다. reviewdog는 정적 분석 도구의 결과를 다양한 플랫폼으로 자동 전달하는 중개 역할을 수행하며, 이를 통해 리뷰 프로세스의 효율성을 극대화한다.

reviewdog의 동작 원리

기존의 정적 분석 도구들은 각자 독립적인 출력 형식을 가지고 있어 CI 파이프라인에서 일관되게 활용하기 어려웠다. reviewdog는 이러한 도구들의 출력을 표준화된 형태로 변환한 뒤, 코드 호스팅 서비스의 API를 통해 리뷰 코멘트로 게시한다. 이 과정에서 diff 정보와 비교하여 실제로 변경된 코드 범위 내의 문제점만 선별적으로 보고할 수 있다.

설치 및 환경 구성

Go 모듈 환경이 준비되어 있다면 바이너리 설치 없이도 바로 사용할 수 있다.

go install github.com/reviewdog/reviewdog/cmd/reviewdog@latest

특정 버전을 고정해야 하는 경우에는 다음과 같이 태그를 지정한다.

go install github.com/reviewdog/reviewdog/cmd/reviewdog@v0.17.0

컨테이너 환경에서는 공식 이미지를 활용하는 것이 권장된다.

docker pull ghcr.io/reviewdog/reviewdog:latest

설정 파일 구조화

프로젝트 루트에 .reviewdog.yml을 배치하여 실행 환경을 선언적으로 관리할 수 있다. 다음은 여러 개의 린터를 동시에 구성하는 예시이다.

runner:
  py-lint:
    cmd: pylint --output-format=text src/**/*.py
    format: pylint
    level: warning
  shell-check:
    cmd: shellcheck -f gcc scripts/*.sh
    format: gcc
    level: error

각 runner는 독립적으로 실행되며, 결과는 하나의 인터페이스에서 통합되어 표시된다.

GitHub Actions 연동

Pull Request 생성 시점에 자동으로 분석이 트리거되도록 워크플로우를 구성한다. GITHUB_TOKEN의 권한 범위에 주의해야 한다.

name: automated-review

on:
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup reviewdog
        uses: reviewdog/action-setup@v1
      - name: Execute linter with reporting
        env:
          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          flake8 src/ | reviewdog \
            -f=flake8 \
            -reporter=github-pr-review \
            -filter-mode=added \
            -fail-on-error=false

-filter-mode=added 옵션은 PR에서 새로 추가된 라인만 대상으로 삼아, 기존 코드베이스의 기술 부채로 인해 리뷰가 과도하게 생성되는 것을 방지한다.

핵심 실행 모드

reviewdog는 필터 모드를 통해 보고 대상 범위를 조절한다.

모드	설명
added	PR/MR에서 새로 추가된 라인만 검사
diff_context	변경된 파일의 diff 컨텍스트 범위 내 문제 보고
file	변경된 파일 전체에서 발생한 문제 보고
nofilter	프로젝트 전체를 대상으로 무조건 보고

팀의 성숙도와 코드베이스 상태에 따라 단계적으로 모드를 전환하는 전략이 유효하다.

사용자 정의 포맷 적용

지원하지 않는 분석 도구의 경우 -f=diff 또는 -f=tty를 활용하여 직접 파싱 규칙을 정의할 수 있다. 정규 표현식을 통해 파일 경로, 라인 번호, 메시지, 심각도를 추출한다.

my-custom-linter --format=gcc | reviewdog \
  -f=gcc \
  -reporter=github-pr-review \
  -level=error

고급 활용: 리뷰 요약과 체크 실행

대규모 프로젝트에서는 PR 본문에 개요를 남기고, 상세 내용은 체크 탭에서 확인할 수 있도록 분리하는 것이 사용자 경험에 유리하다.

reviewdog \
  -reporter=github-check \
  -filter-mode=file \
  -level=warning \
  -tee

-tee 플래그는 파이프라인의 중간 출력을 그대로 터미널에 노출하여 디버깅을 용이하게 한다.

로컬 개발 환경에서의 활용

CI 파이프라인에만 의존하면 피드백 사이클이 길어진다. 로컬에서 동일한 규칙으로 사전 검증하려면 local 리포터를 사용한다.

reviewdog -f=eslint -diff="git diff HEAD~1"

이 방식은 커밋 전 훅(pre-commit hook)과 결합하여 코드 저장 이전에 품질 문제를 차단하는 용도로 활용된다.

문제 해결 접근법

API 요청 한도 초과나 인증 실패가 발생하는 경우, REVIEWDOG_GITHUB_API_TOKEN 환경 변수의 유효성을 먼저 확인한다. Fine-grained 토큰을 사용하는 경우 저장소 권한과 Pull Request 접근 범위가 적절히 설정되어 있어야 한다.

분석 도구의 출력이 reviewdog에서 인식되지 않으면 -f=tty로 전환하여 원본 출력을 직접 확인한 뒤, 적합한 파서를 선택하거나 커스텀 정규식을 적용한다.

태그: reviewdog GitHub Actions CI/CD 정적 분석 코드 품질

8월 3일 04:46에 게시됨

괴물 클럽