[공식문서읽기] Claude Code + GitHub Actions 가이드 - @claude 한마디로 PR 자동 생성부터 코드 리뷰까지

GitHub에서 PR이나 이슈 댓글에 @claude만 쓰면 AI가 코드를 분석하고, 풀 리퀘스트를 만들고, 버그를 고쳐준다면 어떨까요? Claude Code GitHub Actions가 바로 그 역할을 합니다. Anthropic의 Claude Agent SDK를 기반으로 구축된 이 도구는 GitHub 워크플로우에 AI 기반 자동화를 제공하며, 몇 분 안에 설정을 완료할 수 있습니다.

---

Claude Code GitHub Actions란?

Claude Code GitHub Actions는 GitHub의 CI/CD 파이프라인에 Claude AI를 직접 통합하는 공식 GitHub Action입니다. anthropics/claude-code-action@v1이라는 액션을 워크플로우에 추가하면, 팀원들이 이슈나 PR에서 @claude를 멘션하는 것만으로 AI 코딩 어시스턴트를 호출할 수 있습니다.

핵심 특징

• 즉시 PR 생성: 필요한 변경 사항을 설명하면 Claude가 모든 코드 변경이 포함된 완전한 PR을 자동으로 생성합니다
• 자동화된 코드 구현: 이슈에 기능 요구사항을 적으면 Claude가 작동하는 코드로 변환합니다
• 프로젝트 표준 준수: CLAUDE.md 파일에 정의된 코딩 규칙과 기존 코드 패턴을 존중합니다
• 간단한 설정: API 키 하나와 워크플로우 파일 하나면 시작할 수 있습니다
• 기본적으로 안전: 모든 코드 실행은 GitHub 호스팅 러너에서 격리되어 수행됩니다

---

설정 방법

Claude Code GitHub Actions를 시작하는 방법은 두 가지입니다.

방법 1: 자동 설정 (권장)

터미널에서 Claude Code를 열고 아래 명령어를 실행하면 됩니다.

claude
# Claude Code 실행 후
/install-github-app

이 명령어가 GitHub 앱 설치와 시크릿 설정을 자동으로 안내합니다. 저장소 관리자 권한이 필요하며, 직접 Claude API를 사용하는 경우에만 이 방법을 사용할 수 있습니다.

방법 2: 수동 설정

자동 설정이 되지 않거나 세밀한 제어가 필요한 경우 수동으로 설정할 수 있습니다.

1단계: Claude GitHub 앱 설치

GitHub Apps에서 Claude 앱을 저장소에 설치합니다. 앱은 다음 권한을 요청합니다.

• Contents: 읽기 및 쓰기 (저장소 파일 수정)
• Issues: 읽기 및 쓰기 (이슈 응답)
• Pull requests: 읽기 및 쓰기 (PR 생성 및 변경 사항 푸시)

2단계: API 키 등록

Anthropic 콘솔에서 발급받은 ANTHROPIC_API_KEY를 저장소의 GitHub Secrets에 추가합니다.

• 저장소 Settings → Secrets and variables → Actions
• “New repository secret” 클릭
• Name: ANTHROPIC_API_KEY, Value: API 키 입력

3단계: 워크플로우 파일 생성

.github/workflows/claude.yml 파일을 생성합니다.

---

기본 워크플로우 작성

가장 기본적인 워크플로우 파일은 아래와 같습니다. 이 설정만으로 PR과 이슈 댓글에서 @claude 멘션에 Claude가 응답합니다.

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

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

트리거 이벤트 설명

• issue_comment: 이슈에 새 댓글이 달릴 때 실행
• pull_request_review_comment: PR 리뷰 댓글이 달릴 때 실행
• 별도의 mode 설정 없이도 v1에서는 @claude 멘션을 자동으로 감지합니다

---

실전 활용 사례

1. 자동 코드 리뷰

PR이 생성되거나 업데이트될 때 자동으로 코드 리뷰를 수행합니다.

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"

2. 이슈 기반 기능 구현

이슈 댓글에서 @claude를 호출하여 기능 구현을 요청합니다.

@claude implement this feature based on the issue description
@claude 이 이슈에 설명된 기능을 구현해줘

Claude는 이슈 내용을 분석한 뒤, 필요한 코드 변경을 포함한 PR을 자동으로 생성합니다.

3. 버그 수정

@claude fix the TypeError in the user dashboard component
@claude 로그인 화면에서 발생하는 null 에러 수정해줘

4. 일일 자동 보고서

스케줄 기반으로 매일 아침 어제의 커밋과 오픈 이슈를 요약합니다.

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model claude-opus-4-5-20251101"

---

주요 구성 옵션

액션 파라미터

• prompt: Claude에게 전달할 지침 (텍스트 또는 /review 같은 내장 명령)
• claude_args: Claude Code CLI에 전달할 인수
• anthropic_api_key: Anthropic API 키 (직접 API 사용 시 필수)
• github_token: GitHub API 액세스용 토큰
• trigger_phrase: 사용자 정의 트리거 구문 (기본값: @claude)
• use_bedrock: AWS Bedrock 사용 여부
• use_vertex: Google Vertex AI 사용 여부

claude_args 활용

claude_args를 통해 다양한 CLI 옵션을 전달할 수 있습니다.

claude_args: "--max-turns 10 --model claude-sonnet-4-5-20250929"

자주 쓰는 옵션들은 아래와 같습니다.

• --max-turns: 최대 대화 턴 수 (기본값 10)
• --model: 사용할 모델 지정
• --append-system-prompt: 추가 시스템 프롬프트
• --allowed-tools: 허용할 도구 목록
• --disallowed-tools: 차단할 도구 목록
• --debug: 디버그 출력 활성화

---

CLAUDE.md로 프로젝트 표준 정의하기

Claude가 프로젝트의 규칙을 따르게 하려면 저장소 루트에 CLAUDE.md 파일을 생성합니다. 이 파일에 코딩 스타일, 리뷰 기준, 프로젝트별 규칙을 정의하면 Claude가 PR 생성과 코드 리뷰 시 해당 기준을 따릅니다.

# 프로젝트 가이드라인

## 코딩 스타일
- TypeScript 사용
- 함수형 컴포넌트 선호
- 변수명은 camelCase

## 리뷰 기준
- 보안 취약점 확인 필수
- 테스트 코드 포함 여부 확인
- 성능 영향 평가

이 방식은 팀 전체의 코딩 표준을 AI에게 일관되게 전달하는 좋은 방법입니다.

---

베타에서 v1.0으로 업그레이드

기존에 베타 버전을 사용하고 있었다면 몇 가지 변경이 필요합니다.

주요 변경 사항

• @beta → @v1: 액션 버전 태그 변경
• mode 파라미터 제거: v1에서는 interactive/automation 모드를 자동 감지합니다
• direct_prompt → prompt: 프롬프트 파라미터명 변경
• custom_instructions → claude_args: CLI 옵션으로 통합

변경 전 (베타)

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Follow our coding standards"
    max_turns: "10"
    model: "claude-sonnet-4-5-20250929"

변경 후 (v1.0 GA)

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "Follow our coding standards"
      --max-turns 10
      --model claude-sonnet-4-5-20250929

---

엔터프라이즈 환경: AWS Bedrock & Google Vertex AI

직접 Anthropic API 대신 자사의 클라우드 인프라를 통해 Claude를 사용할 수도 있습니다.

AWS Bedrock 연동

OIDC 인증을 사용하여 정적 자격 증명 없이 안전하게 연결합니다.

steps:
  - name: Configure AWS Credentials (OIDC)
    uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
      aws-region: us-west-2

  - uses: anthropics/claude-code-action@v1
    with:
      github_token: ${{ steps.app-token.outputs.token }}
      use_bedrock: "true"
      claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0'

필요한 것들은 아래와 같습니다.

• Amazon Bedrock에서 Claude 모델 액세스 승인
• GitHub OIDC Identity Provider 설정
• Bedrock 권한이 있는 IAM 역할 생성

Google Vertex AI 연동

Workload Identity Federation을 사용하여 서비스 계정 키 없이 인증합니다.

steps:
  - name: Authenticate to Google Cloud
    uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
      service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

  - uses: anthropics/claude-code-action@v1
    with:
      github_token: ${{ steps.app-token.outputs.token }}
      use_vertex: "true"
      claude_args: '--model claude-sonnet-4@20250514'
    env:
      ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
      CLOUD_ML_REGION: us-east5

---

비용과 최적화

Claude Code GitHub Actions를 사용하면 두 가지 비용이 발생합니다.

GitHub Actions 비용

• GitHub 호스팅 러너에서 실행되므로 Actions 분(minutes)이 소비됩니다
• 무료 플랜은 월 2,000분, Pro 플랜은 월 3,000분이 제공됩니다

API 토큰 비용

• 각 Claude 호출마다 프롬프트와 응답 길이에 따라 토큰이 소비됩니다
• 코드베이스 크기와 작업 복잡도에 따라 비용이 달라집니다

비용 절감 팁

• --max-turns 값을 적절히 설정하여 불필요한 반복을 방지합니다
• 워크플로우 레벨에서 타임아웃을 설정합니다
• GitHub의 concurrency 제어를 활용하여 병렬 실행을 제한합니다
• 구체적인 @claude 명령을 사용하여 불필요한 API 호출을 줄입니다

---

보안 모범 사례

API 키 관리

• 절대 API 키를 코드에 직접 하드코딩하지 마세요
• 반드시 GitHub Secrets를 사용하세요: ${{ secrets.ANTHROPIC_API_KEY }}
• 워크플로우 파일에서 직접 키를 노출하지 마세요

권한 최소화

• 워크플로우의 permissions 블록에서 필요한 권한만 부여합니다
• Claude의 도구 사용을 --allowed-tools나 --disallowed-tools로 제한할 수 있습니다

코드 리뷰

• Claude가 생성한 코드는 반드시 병합 전에 사람이 검토해야 합니다
• 비공개 발행이나 초안 PR 기능을 활용하여 검토 과정을 거치세요

---

트러블슈팅

Claude가 @claude에 응답하지 않을 때

• GitHub 앱이 해당 저장소에 설치되어 있는지 확인합니다
• 워크플로우 파일이 .github/workflows/ 경로에 있는지 확인합니다
• ANTHROPIC_API_KEY 시크릿이 올바르게 설정되었는지 확인합니다
• 댓글에 @claude(슬래시가 아닌 골뱅이)가 포함되어 있는지 확인합니다

CI가 Claude 커밋에서 실행되지 않을 때

• GitHub 앱을 사용하고 있는지 확인합니다 (기본 GITHUB_TOKEN이 아닌)
• 워크플로우 트리거에 필요한 이벤트가 포함되어 있는지 점검합니다

인증 에러 발생 시

• API 키가 유효한지 확인합니다
• Bedrock/Vertex 사용 시 자격 증명 설정을 재확인합니다
• 시크릿 이름이 워크플로우 파일에서 정확히 일치하는지 확인합니다

---

마무리

Claude Code GitHub Actions는 개발 워크플로우에 AI를 자연스럽게 통합할 수 있는 강력한 도구입니다. 단 몇 줄의 YAML 설정으로 @claude 한마디에 코드 리뷰, 기능 구현, 버그 수정이 가능해집니다. CLAUDE.md를 활용해 프로젝트 표준을 정의하고, GitHub Secrets로 API 키를 안전하게 관리하면 팀 전체의 개발 생산성을 크게 높일 수 있습니다.

AWS Bedrock이나 Google Vertex AI와의 연동도 지원하므로, 엔터프라이즈 환경에서도 데이터 거버넌스를 유지하면서 AI 자동화의 혜택을 누릴 수 있습니다.

---

참고 자료

• Claude Code GitHub Actions 공식 문서
• anthropics/claude-code-action GitHub 저장소
• Claude Code Action - GitHub Marketplace
• 워크플로우 예제 파일 (claude.yml)
• 보안 설명서
• Claude Code Action 사용 가이드

이 글은 Claude Code를 활용하여 작성되었습니다.