Claude Code GitHub Actions

Claude Code를 GitHub 워크플로우에 통합하여 AI 기반 자동화를 구현하는 방법을 알아보세요.

Claude Code GitHub Actions는 GitHub 워크플로우에 AI 기반 자동화를 제공합니다. PR이나 이슈에서 @claude를 멘션하면 Claude가 코드를 분석하고, PR을 생성하고, 기능을 구현하고, 버그를 수정할 수 있습니다.

왜 Claude Code GitHub Actions를 사용하나요?

• 즉각적인 PR 생성: 필요한 내용을 설명하면 Claude가 완전한 PR을 생성
• 자동화된 코드 구현: 단일 명령으로 이슈를 작동하는 코드로 변환
• 표준 준수: Claude가 CLAUDE.md 가이드라인과 기존 코드 패턴을 존중
• 간단한 설정: 인스톨러와 API 키로 몇 분 만에 시작
• 기본적으로 안전: 코드는 GitHub 러너에 보관

빠른 설정

터미널에서 Claude Code를 열고 다음 명령을 실행하세요:

/install-github-app

이 명령이 GitHub 앱과 필요한 시크릿 설정을 안내합니다.

참고: 저장소 관리자여야 합니다. 직접 Claude API 사용자에게만 사용 가능합니다.

수동 설정

1. Claude GitHub 앱 설치: https://github.com/apps/claude

   • 필요한 권한: Contents (읽기/쓰기), Issues (읽기/쓰기), Pull requests (읽기/쓰기)

2. ANTHROPIC_API_KEY를 저장소 시크릿에 추가

3. 워크플로우 파일 복사: examples/claude.yml을 .github/workflows/에 복사

베타에서 업그레이드

v1.0에서 주요 변경 사항:

이전 (베타):

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "이 PR에서 보안 문제를 검토해줘"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "코딩 표준을 따르세요"
    max_turns: "10"

새로운 버전 (v1.0):

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "이 PR에서 보안 문제를 검토해줘"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "코딩 표준을 따르세요"
      --max-turns 10

예시 사용 사례

기본 워크플로우

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 }}
          # 댓글의 @claude 멘션에 응답

스킬 사용

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"

커스텀 자동화

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: "어제의 커밋과 열린 이슈 요약을 생성해줘"
          claude_args: "--model opus"

이슈/PR 댓글에서 사용

@claude 이슈 설명을 기반으로 이 기능을 구현해줘
@claude 이 엔드포인트의 사용자 인증을 어떻게 구현해야 하나?
@claude 사용자 대시보드 컴포넌트의 TypeError를 수정해줘

모범 사례

CLAUDE.md 설정

저장소 루트에 CLAUDE.md 파일을 만들어 코드 스타일 가이드라인, 검토 기준, 프로젝트 규칙, 선호 패턴을 정의하세요.

보안 고려 사항

경고: API 키를 저장소에 직접 커밋하지 마세요.

# 항상 GitHub 시크릿을 사용하세요
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

비용 최적화

• 불필요한 API 호출을 줄이기 위해 구체적인 @claude 명령 사용
• claude_args에서 --max-turns 설정으로 과도한 반복 방지
• 워크플로우 수준 타임아웃 설정
• GitHub의 동시성 제어로 병렬 실행 제한

AWS Bedrock & Google Vertex AI와 함께 사용하기

엔터프라이즈 환경에서는 자체 클라우드 인프라와 함께 사용할 수 있습니다.

AWS Bedrock 워크플로우

name: Claude PR Action
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]

jobs:
  claude-pr:
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - uses: actions/checkout@v4
      - 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:
          use_bedrock: "true"
          claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'

Google Vertex AI 워크플로우

name: Claude PR Action
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]

jobs:
  claude-pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Authenticate to Google Cloud
        id: auth
        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:
          use_vertex: "true"
          claude_args: '--model claude-sonnet-4@20250514 --max-turns 10'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5

액션 파라미터 레퍼런스

*직접 Claude API에 필요, Bedrock/Vertex에는 불필요

문제 해결

@claude 명령에 응답 없음

• GitHub 앱이 올바르게 설치되었는지 확인
• 워크플로우가 활성화되어 있는지 확인
• API 키가 저장소 시크릿에 설정되어 있는지 확인
• 댓글에 @claude가 포함되어 있는지 확인 (/claude가 아닌)

Claude의 커밋에서 CI 실행 안 됨

• GitHub 앱 또는 커스텀 앱 사용 확인 (Actions 사용자 아님)
• 워크플로우 트리거에 필요한 이벤트 포함 여부 확인

관련 항목

• GitLab CI/CD 통합
• Hooks 시스템
• CI/CD 및 자동화