Claude Code GitHub 연동: Actions로 PR 리뷰와 이슈 수정 자동화

가장 큰 변화는 개발자가 작업이 끝날 때까지 자리를 지킬 필요가 줄어든다는 점입니다. 이전에는 개발자가 저장소를 열고 Claude를 실행한 뒤, 로컬 세션을 유지하면서 결과를 GitHub로 옮겨야 했습니다. Action을 쓰면 메인테이너가 범위를 정해 요청을 남기고, 나중에 댓글이나 변경 제안을 확인하면 됩니다. 개발자의 근무 시간 밖에서도 작업을 시작할 수 있지만, 결과를 검토하는 시간은 여전히 필요합니다.

이 가이드는 2026년 10월 15일에 확인한 Anthropic의 최신 문서를 기준으로 작성했습니다. 아래 워크플로는 처음 도입할 때 쓰도록 의도적으로 범위를 좁힌 설정입니다. 모든 이슈를 사람의 개입 없이 해결할 수 있다는 뜻은 아닙니다.

저장소에서 요청에 응답하는 어시스턴트 만들기

GitHub App은 출입증, 워크플로는 작업 지시서, 러너는 임시 작업용 컴퓨터라고 생각하면 됩니다. 워크플로는 GitHub에 언제 작업을 시작할지 알려 주는 설정 파일이고, 러너는 실제로 작업을 수행하는 머신입니다.

이 액션은 이슈와 풀 리퀘스트의 멘션에 응답할 수 있습니다. 대신 prompt를 지정하면 자동 작업으로 실행됩니다. 소규모 팀이라면 모든 변경에 리뷰 비용을 들이기 전에, 명시적인 요청부터 사용하면서 어떤 작업에 도움이 되는지 확인하는 편이 가장 쉽습니다. 액션 사용법.

Claude Code GitHub 연동, 앱 설치부터 워크플로 병합까지

저장소 관리자 권한으로 안내에 따라 설치합니다. 설치된 GitHub CLI에서 gh auth login으로 인증하고, 저장소 안에서 claude를 연 다음 /install-github-app을 실행합니다. 사용할 워크플로와 API 키 또는 구독 인증 방식을 선택한 뒤, 준비된 워크플로 PR을 만들고 병합합니다. 설치는 로컬에서 진행하지만 이후 작업은 GitHub에서 실행됩니다. 공식 빠른 설정 가이드.

수동으로 설정해도 결과는 같습니다.

1. 선택한 저장소에 Claude GitHub App을 설치합니다.
2. 저장소의 Settings → Secrets and variables → Actions를 열고 아래 표에서 인증 시크릿 하나를 골라 추가합니다.
3. Anthropic의 동작 예제를 .github/workflows/claude.yml에 복사하고, 인증 방식에 맞는 입력값을 선택한 뒤 파일을 병합합니다.
4. @claude와 구체적인 요청이 담긴 댓글을 남깁니다.

공식 수동 설치 절차에 어떤 인증 자격 증명을 선택할지 명확히 덧붙인 순서입니다. 액션 설정 가이드.

구독 인증을 사용하려면 로컬에서 claude setup-token을 실행하고 출력된 값을 시크릿으로 저장합니다. Anthropic은 Pro, Max, Team, Enterprise 요금제에서 이 방식을 안내합니다. 생성된 토큰의 유효기간은 1년이므로 갱신 담당자를 정해 두어야 합니다. 토큰 인증.

과금 방식은 인증 자격 증명에 따라 달라집니다. API 키로 실행하면 API 요금이 청구되고, OAuth 토큰으로 실행하면 Claude 구독 사용량에 반영됩니다. GitHub Actions 러너 사용량은 별도로 계산됩니다. 구독 토큰은 이를 생성한 개인에게 귀속되므로, Anthropic은 여러 저장소가 시크릿을 공유할 때 API 키를 사용할 것을 권장합니다. 인증과 비용.

기본 앱 설정에는 GitHub 개인 액세스 토큰이 필요하지 않습니다. GitHub 접근 권한과 Claude 인증은 별개입니다. 전자는 앱이 제공하고, 후자는 선택한 시크릿이 담당합니다. 인증 입력값.

멘션으로 실행하는 작은 워크플로부터 시작하기

이 설정은 신뢰할 수 있는 팀 저장소에서 소규모 파일 변경에 사용합니다. 파일을 읽고 수정할 수 있으며 GitHub API를 통해 커밋할 수 있습니다. Claude에 셸 툴을 제공하지 않으므로 이 설정에서는 테스트 명령을 실행할 수 없습니다. 변경 제안에 대해 자동 검사를 수행하는 기존 CI가 테스트 실행을 맡도록 유지합니다.

다음 내용을 .github/workflows/claude.yml로 저장합니다. 액션 참조인 actions/checkout@v6와 anthropics/claude-code-action@v1은 Anthropic의 현재 예제에 나오는 버전입니다. 최대 5턴과 15분 타임아웃은 시작 단계에서 이 글이 선택한 값이며, Anthropic의 기본값이 아닙니다. 공식 워크플로.

name: Claude on request
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 15
    concurrency:
      group: claude-small-team
      cancel-in-progress: false
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          use_commit_signing: true
          claude_args: |
            --max-turns 5
            --tools "Read,Glob,Grep,Edit,Write"
            --disallowedTools "Bash,WebFetch,WebSearch"

구독 사용량으로 처리하려면 anthropic_api_key 줄을 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}으로 바꿉니다. 인증 방식은 하나만 전달합니다. 기본 GitHub App 인증에 필요한 id-token: write는 유지합니다. 공식 워크플로와 인증, 입력값 레퍼런스.

각 제어 항목은 역할이 다릅니다.

• --tools는 Claude가 사용할 수 있는 내장 툴을 선택합니다. Read, Glob, Grep은 파일을 살펴보고, Edit와 Write는 파일을 변경합니다. 액션이 GitHub와 통신할 때 별도로 연결해 쓰는 MCP 툴은 이 옵션으로 제한되지 않습니다.
• --allowedTools는 지정한 툴을 확인 요청 없이 사용할 수 있도록 허용합니다. 전체 툴을 제한하는 완전한 허용 목록은 아닙니다. 여기서는 --disallowedTools 줄을 명시해 셸과 웹 툴을 차단합니다.
• --max-turns는 에이전트의 작업 반복 횟수를 제한합니다. 토큰 수나 비용의 상한을 정하지는 않으며, 한도에 도달하면 작업을 끝내지 못한 채 오류로 실행이 종료될 수 있습니다. CLI 레퍼런스.

use_commit_signing: true를 설정하면 GitHub API를 통해 커밋합니다. 덕분에 이 설정에서는 Claude에 셸 기반 git 명령을 허용하지 않고도 변경 사항을 저장할 수 있습니다. 별도의 서명 시크릿도 필요하지 않습니다. 액션의 GitHub 툴은 계속 사용할 수 있으므로 이 설정에는 쓰기 기능이 있습니다. 커밋 서명, 액션 구현.

고정된 동시 실행 그룹은 저장소마다 이 워크플로의 작업 하나만 실행되도록 제한합니다. 기본 대기열 동작에서는 새 대기 요청이 기존 대기 요청을 대체할 수 있으므로, 작업을 빠짐없이 보관하는 영속적인 대기열로 볼 수는 없습니다. 타임아웃은 준비 과정을 포함한 전체 작업 경과 시간을 제한합니다. GitHub 동시 실행 제어, 워크플로 문법.

@claude review this PR for missing permission checks; report findings without changing files라고 요청해 봅니다. 이슈에서는 @claude fix the null handling described above, change only the parser and its regression test, and state which checks were not run을 시도해 볼 수 있습니다.

기본적으로 실행을 요청하는 사람에게 저장소 쓰기 권한이 있어야 하며, 봇은 차단됩니다. 이슈 수정 작업에서는 브랜치와 사람이 PR을 만들 수 있는 링크가 제공된다고 예상해야 합니다. 팀 지침에도 이 차이를 분명히 적어 둡니다. 액션 보안.

시험 운영 후 AI 코드 리뷰 자동화 추가하기

PR 자동 리뷰를 사용하려면 /install-github-app 설정 과정에서 리뷰 워크플로를 선택합니다. 이 워크플로의 코드 리뷰 플러그인은 --comment와 아래의 댓글 툴 허용 설정을 사용해 발견 사항을 게시합니다. 공식 리뷰 예제.

별도로 구성하는 리뷰 워크플로에는 다음 액션 입력값이 포함됩니다.

plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
plugins: "code-review@claude-code-plugins"
prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
claude_args: >-
  --max-turns 5
  --allowedTools "mcp__github_inline_comment__create_inline_comment"

이 입력값은 앞서 소개한 멘션 워크플로가 아니라 공식 pull_request 워크플로 안에서 사용합니다. 해당 워크플로의 체크아웃, 인증, 작업 권한을 유지하고 작업 타임아웃을 추가합니다. if: github.event.pull_request.head.repo.full_name == github.repository 조건으로 포크 PR은 건너뜁니다. 턴 제한은 시험 운영용 설정으로 취급해야 합니다. 턴을 모두 소진한 리뷰는 완료된 리뷰가 아닙니다. 문서에 나온 리뷰 스킬은 초안을 비롯한 일부 PR도 건너뜁니다.

앱 설치 범위와 툴 사용 범위는 따로 관리하기

처음에는 선택한 저장소에만 앱을 설치합니다. 공식 Claude App은 여러 Claude 기능에서 권한을 공유하며, GitHub에서는 그 권한 중 일부만 골라 승인할 수 없습니다. YAML의 permissions 블록을 좁게 설정해도 앱 설치 권한의 범위가 줄어들지는 않습니다. 앱 권한 모델.

설치 시 요구하는 권한이 너무 넓다면 Contents, Issues, Pull requests 접근 권한을 갖춘 커스텀 앱 방식으로 구성합니다. 이 방식에는 APP_ID와 APP_PRIVATE_KEY 시크릿, 앱 토큰을 생성해 github_token으로 전달하는 단계가 추가됩니다. 고정된 Claude API 키를 없앨 준비가 된 팀을 위해, 설정 가이드는 GitHub 작업의 신원을 짧은 수명의 API 접근 권한으로 교환하는 워크로드 ID 페더레이션도 설명합니다. 커스텀 앱과 페더레이션 설정.

리뷰 우선순위, 변경이 허용된 영역, 수정 결과에 반드시 포함할 근거를 짧게 정리한 CLAUDE.md를 추가합니다. 지침은 작업 방향을 안내하고, 저장소 권한과 툴 제한은 접근 범위를 강제합니다. 무인 실행을 활성화하기 전에 수명 주기 이벤트마다 명령을 자동 실행하는 훅이나 추가 툴 서버가 설정되어 있는지도 검토합니다. 프로젝트 지침. Claude Code 리뷰 가이드에서는 전반적인 도입 판단을 다루며, 슬래시 명령어 가이드에서는 설정 중 사용하는 명령어를 설명합니다.

우선순위별로 살펴보는 여섯 가지 활용법

요청을 명확하게 설명할 수 있고 결과도 쉽게 확인할 수 있는 작업부터 시작합니다. 다음은 활용 방안이며, 측정된 절감 효과나 보장된 성과는 아닙니다.

시작용 설정에서는 의존성을 설치하거나 테스트 스위트를 실행할 수 없습니다. 이런 작업이 필요하다면 신뢰할 수 있는 코드용 실행 설정을 별도로 검토해 추가하고, 구체적인 명령 권한과 독립적인 제한을 둡니다. 허용된 테스트 명령도 저장소의 코드를 실행합니다. 이름이 익숙하다는 이유만으로 그 코드까지 안전해지는 것은 아닙니다.

트리거를 늘리기 전에 해결해야 할 문제

포크 PR에서는 시크릿에 접근하지 못할 수 있습니다. GitHub는 일반적으로 포크에서 발생한 pull_request 및 pull_request_review_comment 실행에 시크릿을 제공하지 않습니다. 이런 작업에서 Claude 인증 정보가 비어 있는 것은 신뢰 경계를 지키기 위한 동작입니다. 시크릿을 얻으려고 pull_request_target으로 바꾼 뒤 포크의 코드를 실행해서는 안 됩니다. 메인테이너가 시작한 issue_comment 작업에도 시크릿이 제공될 수 있으므로, 댓글 작성자를 신뢰할 수 있다는 이유만으로 PR의 파일까지 신뢰해서는 안 됩니다. GitHub의 포크 보안 가이드.

툴을 제한해도 프로젝트 시작 코드는 무력화되지 않습니다. 액션은 일부 Claude 설정을 베이스 브랜치에서 복원하지만, 스크립트와 다른 프로젝트 파일은 여전히 PR에서 가져올 수 있습니다. Claude에 허용한 툴뿐 아니라 훅과 툴 서버 설정도 점검해야 합니다. 액션의 신뢰 경계.

러너 사용 시간도 별도로 관리해야 합니다. 공개 저장소에서는 표준 GitHub 호스팅 러너를 무료로 사용할 수 있습니다. 비공개 저장소에는 요금제별 기본 제공량과 초과 사용 요금이 적용됩니다. 결제 수단 없이 제공량을 소진하면 작업이 중단될 수 있습니다. Claude 사용량과 함께 Actions 사용량 페이지도 확인합니다. GitHub Actions 과금.

올바른 워크플로도 요청 한도 때문에 중단될 수 있습니다. API 한도는 분당 요청 수와 입력·출력 토큰 수에 적용됩니다. 토큰은 모델이 처리하는 텍스트의 조각입니다. retry-after가 포함된 429 응답을 받았다면 기다렸다가 재시도하고 동시 실행 작업 수를 줄입니다. 해당 헤더 없이 요금 등급의 지출 한도로 발생한 429라면 반복 실행 대신 결제나 한도 문제를 해결해야 합니다. 구독 인증에도 해당 요금제의 사용량 한도가 적용됩니다. API 요청 한도, Claude 사용량 한도.

봇이 응답하지 않는 문제와 CI가 실행되지 않는 문제는 다릅니다. 응답이 없다면 기본 브랜치에 워크플로가 있는지, Actions가 활성화되어 있는지, 시크릿이 입력값과 맞는지, 댓글 작성자에게 쓰기 권한이 있는지 확인합니다. 멘션은 @claude 전체를 입력해야 합니다. 후속 CI가 실행되지 않는다면 앱 인증을 github_token: ${{ secrets.GITHUB_TOKEN }}으로 바꾼 사람이 있는지 확인합니다. GitHub는 이 토큰으로 생성한 여러 이벤트의 후속 실행을 막으며, 일부 PR 워크플로에는 승인이 필요합니다. GitHub 토큰의 동작.

이 워크플로를 바탕으로 만들 수 있는 두 가지 서비스

가장 유망한 기회는 소규모 팀을 위한 리뷰 환경 구축·관리 서비스입니다. 구매자는 유용한 발견 사항, 명확한 책임 소재, 예측 가능한 운영 한도를 원하는 엔지니어링 리드입니다. 2026년 10월 15일에 조회한 DataForSEO의 미국 영어 검색 추정치에서 “ai code review”의 월간 검색량은 1,300회였습니다. 관심이 있다는 근거이지 고객 수를 뜻하지는 않습니다. 판매 가능한 초기 버전은 저장소 하나를 구성하고, 리뷰 우선순위를 지침에 반영하며, 과거 PR로 발견 사항을 평가하고, 사용량과 실패 보고서를 지속적으로 제공하는 형태가 될 수 있습니다. 걸림돌은 오탐이 쌓이면서 생기는 피로감입니다. 코드베이스가 바뀌어도 리뷰 품질을 유지하는 일이 지속적인 가치를 만듭니다. 범용 프롬프트를 감싼 정도의 제품으로는 고객이 계속 사용할 이유가 부족합니다.

에이전시를 대상으로 고객 저장소에 재사용할 수 있는 리뷰 정책 패키지도 생각해 볼 수 있습니다. 같은 시장에서 DataForSEO가 추정한 월간 검색량은 “ai code review tools”가 590회, “github ai code review”가 140회입니다. 최소 제품은 재사용 가능한 워크플로, 고객별 지침 템플릿, 인증 자격 증명 담당자 기록, 누락된 제한 설정을 찾는 검사를 묶는 형태가 될 수 있습니다. 에이전시가 인수인계 과정에서도 일관된 설정을 유지하는 데 도움이 될 수 있습니다. 다만 고객마다 권한과 테스트 환경이 다르므로, 템플릿이 계속 유용하려면 유지보수와 평가가 필요합니다. 이 검색어를 사용하는 집단은 서로 겹치므로 검색량을 더해 시장 규모로 계산해서는 안 됩니다.

작업에 맞는 실행 환경 선택하기

저장소 이벤트에 맞춰 작업해야 하고 설정·권한·로그를 CI와 함께 관리하려면 GitHub Actions를 선택합니다. 노트북을 닫은 상태에서도 브라우저로 일회성 작업을 시작하고 방향을 조정하려면 클라우드 세션이 적합합니다. 매일 밤 백로그를 확인하는 것처럼 반복 작업을 저장해 두고 실행하면서, 워크플로 YAML을 관리하는 대신 Claude가 호스팅하는 일정 및 설정 기능을 쓰고 싶다면 예약 루틴을 선택합니다. 루틴은 GitHub 및 API 트리거도 지원하므로, 예약 실행이 필요하다는 이유만으로 Actions를 선택해야 하는 것은 아닙니다. 루틴은 아직 리서치 프리뷰 단계입니다. 클라우드 세션, 루틴.

월요일에는 저장소 관리자가 앱을 설치하고 제한된 워크플로를 병합하도록 합니다. 이미 파악한 버그와 범위를 좁힌 리뷰 요청을 하나씩 맡긴 다음, 결과를 팀의 판단과 비교합니다. 검토에 드는 노력과 사용량에 걸맞은 결과가 확인된 뒤에만 트리거를 확대합니다.

이 워크플로를 팀에 맞게 구축하고 유지관리하려면 AI 자동화 지원을 받아 보세요.