GitHub Actions와 코드 리뷰

관리형 경로: Code Review

가장 간단한 옵션은 Code Review입니다. 이는 Claude GitHub 앱을 통해 풀 리퀘스트를 리뷰하는 Anthropic 호스팅 서비스입니다. 직접 구축하거나 호스팅할 필요가 없습니다. 켜기만 하면 중요한 줄에 바로 인라인 댓글로 발견 사항을 게시하기 시작합니다.

Claude 조직의 Owner가 Claude Code 관리자 설정에서 이를 활성화합니다. Code review 섹션에서 Allow code review 스위치를 찾을 수 있으며, 이를 통해 설정이 시작됩니다.

그 다음 Owner는 Claude GitHub 앱을 설치하고, 앱이 감시할 저장소를 선택하며, 실행 시점을 결정합니다. Owner가 GitHub 조직의 소유자가 아닌 경우, 먼저 누군가 앱을 설치하고 연결해야 합니다. 실행 시점에는 몇 가지 선택지가 있습니다:

• PR이 열릴 때 한 번
• PR에 푸시가 있을 때마다
• 누군가 @claude review라고 댓글을 달 때만

활성화되면 모든 작업은 Anthropic의 인프라에서 실행됩니다. 일련의 리뷰 에이전트가 변경된 줄만 따로 보는 것이 아니라 전체 코드베이스를 기준으로 diff를 분석합니다. 그런 다음 심각도별로 태그가 지정된 인라인 댓글을 특정 줄에 게시하고, 체크 실행에 요약 표를 함께 남깁니다.

다음은 그런 발견 사항 중 하나의 예시입니다. Claude가 남긴 댓글로, 해당 줄에 바로 명확한 설명과 제안된 수정 사항과 함께 표시됩니다.

좋은 점은 발견 사항을 중복 제거하고 순위를 매긴다는 것입니다. 그래서 사소한 지적들이 잔뜩 쌓이는 대신, 정말 주의를 기울일 가치가 있는 몇 가지 실제 문제만 읽게 됩니다.

Code Review가 하는 일과 하지 않는 일

여기서 경계에 대해 기억해 둘 몇 가지가 있습니다:

• PR을 승인하거나 차단하는 일은 절대 하지 않습니다. 판단은 사람의 몫으로 남습니다. Claude는 문제를 표시할 뿐, 결정은 여러분이 합니다.
• 수정 사항을 푸시하지 않습니다. 이 서비스는 발견 사항만 게시합니다.
• Team 및 Enterprise Plan에서 사용할 수 있습니다.

이 서비스는 발견 사항만 게시하므로, 이를 바탕으로 조치를 취하는 것은 여러분의 몫입니다. 코드를 수정하고 푸시하세요. 푸시하기 전에 수정 사항을 확인하려면 자신의 터미널에서 /code-review를 실행하세요. 이는 여러분의 diff에 대해 자체 리뷰를 실행하며, --fix 플래그는 그 리뷰의 발견 사항을 작업 트리에 적용합니다.

직접 구축하는 경로: GitHub Action

Code Review는 리뷰를 처리합니다. 작업이 리뷰를 넘어설 때는 GitHub Action을 사용하세요. 이는 댓글에서 변경 사항을 구현하거나, 예약된 보고서를 실행하는 등 평소라면 워크플로우를 작성했을 만한 커스텀 CI를 위한 것입니다. 이는 PR 댓글, 예약된 작업, 그리고 모든 GitHub 이벤트에서 에이전트를 실행합니다.

설정은 Claude Code 내부에서 시작됩니다. /install-github-app 명령을 실행하세요. 이를 수행하려면 저장소 관리자 권한이 필요합니다. 이 슬래시 명령은 GitHub 앱 설치와 저장소에 Anthropic API 키 시크릿 설정 과정을 안내합니다.

액션 자체는 anthropics/claude-code-action@v1입니다. 실제로 사용하게 될 입력값은 다음과 같습니다:

• anthropic_api_key — 실행이 Claude API를 호출할 때 필요하며, claude_code_oauth_token(Claude 구독에서 발급)으로 인증하거나 워크로드 아이덴티티 페더레이션(저장된 시크릿 없이 Claude Console 서비스 계정을 통해 설정)을 사용하는 경우는 예외입니다. 아래의 클라우드 제공업체와 함께 사용되지 않습니다.
• github_token — 선택 사항입니다. 생략하면 액션은 설정 시 설치한 Claude GitHub 앱으로 인증합니다. 이를 재정의하려는 경우에만 토큰을 전달하세요.
• trigger_phrase — 액션이 댓글에서 감지할 문구입니다. 기본값은 @claude입니다.
• use_bedrock / use_vertex / use_foundry — Claude API 대신 Amazon Bedrock, Google Cloud's Agent Platform, 또는 Microsoft Foundry를 통해 실행을 라우팅하며, API 키 대신 클라우드 계정으로 로그인합니다.
• prompt — 자동화된 실행을 위한 지시문입니다. 이를 설정하면 Claude는 멘션을 기다리지 않고 이벤트에서 바로 실행됩니다. 생략하면 액션은 트리거 문구를 기다립니다.
• claude_args — Claude Code로 그대로 전달되는 CLI 인수 문자열입니다.

@claude에 응답하는 워크플로우

.github/workflows/claude.yaml에 워크플로우를 추가하면 PR 댓글과 이슈 댓글에서 @claude를 감지합니다. 작업의 permissions 아래에 id-token: write를 부여하여 액션이 Claude GitHub 앱으로 로그인할 수 있게 하세요. 핵심 단계는 다음과 같습니다:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    trigger_phrase: "@claude"
    claude_args: "--max-turns 5 --model claude-sonnet-5"

이제 누군가 풀 리퀘스트에 @claude implement the spec in the linked Linear issue라고 작성하면 액션이 이를 감지합니다. Claude는 커밋을 푸시하고 수행한 작업을 설명하는 댓글을 게시합니다.

예약 실행되는 워크플로우

동일한 액션이 일일 요약 보고에도 사용됩니다. 예를 들어 cron 트리거가 UTC 9시에 실행되면, 액션이 prompt를 실행하고 해당 실행의 로그에서 요약 내용을 읽을 수 있습니다. 예약된 실행은 자체적으로 댓글을 게시하지 않습니다. Actions 탭에서 수동으로 실행할 수 있도록 workflow_dispatch 트리거를 추가할 수도 있습니다.

액션이 실행되면 다른 GitHub 워크플로우와 마찬가지로 Actions 탭에서 단계별 진행 상황을 지켜볼 수 있습니다.

claude_args로 실행 조정하기

세부 조정은 claude_args 줄에서 이루어집니다. 알아두면 좋은 몇 가지 옵션은 다음과 같습니다:

• --max-turns 5는 에이전트 루프에 엄격한 상한을 두어 무한히 실행되지 않도록 합니다.
• 권한 모드. 무인 작업의 경우 멈춰서 질문하지 않도록 설정해야 합니다. 답할 사람이 없기 때문입니다.
• 허용된 도구. 작업에 정확히 필요한 것만 주고 그 이상은 주지 마세요. 보고서의 경우 읽기 전용이면 충분합니다.

어느 것을 사용해야 할까요?

간단히 정리하면 다음과 같습니다:

• PR 리뷰의 경우 관리형 경로를 선택하세요. Code Review를 활성화하고 GitHub 앱이 인라인 발견 사항을 게시하도록 한 다음, 코드를 수정하고 푸시하세요.
• 작업이 리뷰 이상인 경우 액션을 사용하세요. 설정에는 /install-github-app을 사용하고, @claude 멘션용 워크플로우 하나, cron용 워크플로우 하나를 두며, 모든 세부 조정은 claude_args에 담으세요.

관리형 서비스로 시작하세요. Claude가 단순히 댓글을 다는 것을 넘어 CI에서 실제로 무언가를 수행해야 하는 순간이 오면 액션으로 전환하세요.