Claude Code GitHub Actions

Claude Code GitHub Actions를 사용하여 Claude Code를 개발 워크플로에 통합하는 방법을 알아보세요

Claude Code GitHub Actions는 GitHub 워크플로에 AI 기반 자동화를 제공합니다. PR이나 이슈에서 간단히 @claude를 멘션하면, Claude가 코드를 분석하고, Pull Request를 생성하고, 기능을 구현하고, 버그를 수정할 수 있습니다 - 모두 프로젝트의 표준을 따르면서 수행됩니다.

참고:

Claude Code GitHub Actions는 Claude
Agent SDK 위에 구축되어 있으며, 이 SDK를 통해 Claude Code를 애플리케이션에 프로그래밍 방식으로 통합할 수 있습니다. SDK를 사용하여 GitHub Actions를 넘어서는 커스텀
자동화 워크플로를 구축할 수 있습니다.

참고:

Claude Opus 4.6이 출시되었습니다. Claude Code GitHub Actions의 기본 모델은 Sonnet입니다. Opus 4.6을 사용하려면 model 파라미터에서 claude-opus-4-6으로 설정하세요.

Claude Code GitHub Actions를 사용하는 이유

• 즉각적인 PR 생성: 필요한 내용을 설명하면, Claude가 모든 필요한 변경 사항이 포함된 완전한 PR을 생성합니다
• 자동화된 코드 구현: 단일 명령으로 이슈를 동작하는 코드로 변환합니다
• 표준 준수: Claude는 CLAUDE.md 가이드라인과 기존 코드 패턴을 준수합니다
• 간편한 설정: 설치 프로그램과 API 키만으로 몇 분 안에 시작할 수 있습니다
• 기본적으로 안전: 코드는 Github의 러너에서 실행됩니다

Claude가 할 수 있는 것

Claude Code는 코드 작업 방식을 변화시키는 강력한 GitHub Action을 제공합니다:

Claude Code Action

이 GitHub Action을 사용하면 GitHub Actions 워크플로 내에서 Claude Code를 실행할 수 있습니다. 이를 활용하여 Claude Code 위에 커스텀 워크플로를 구축할 수 있습니다.

저장소 보기 →

설정

빠른 설정

이 Action을 설정하는 가장 쉬운 방법은 터미널에서 Claude Code를 사용하는 것입니다. Claude를 열고 /install-github-app을 실행하세요.

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

참고:

• GitHub 앱을 설치하고 시크릿을 추가하려면 저장소 관리자여야 합니다
• GitHub 앱은 Contents, Issues, Pull requests에 대한 읽기 및 쓰기 권한을 요청합니다
• 이 빠른 설정 방법은 Claude API 직접 사용자만 이용할 수 있습니다.
  AWS Bedrock이나 Google Vertex AI를 사용하는 경우 AWS Bedrock 및 Google Vertex AI와 함께 사용하기
  섹션을 참조하세요.

수동 설정

/install-github-app 명령이 실패하거나 수동 설정을 선호하는 경우, 다음 수동 설정 지침을 따르세요:

1. Claude GitHub 앱을 저장소에 설치하세요: https://github.com/apps/claude

   Claude GitHub 앱에는 다음 저장소 권한이 필요합니다:

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

   보안 및 권한에 대한 자세한 내용은 보안 문서를 참조하세요.

2. ANTHROPIC_API_KEY를 저장소 시크릿에 추가하세요 (GitHub Actions에서 시크릿 사용 방법 알아보기)

3. 워크플로 파일을 복사하세요 examples/claude.yml에서 저장소의 .github/workflows/ 디렉토리로 복사합니다

팁:

빠른 설정이나 수동 설정을 완료한 후, 이슈나 PR 댓글에서 @claude를 태그하여 Action을 테스트하세요.

베타에서 업그레이드

주의:

Claude Code GitHub Actions v1.0은 베타 버전에서 v1.0으로 업그레이드하기 위해 워크플로 파일을 업데이트해야 하는 주요 변경 사항을 도입합니다.

현재 Claude Code GitHub Actions의 베타 버전을 사용하고 있다면, GA 버전으로 워크플로를 업데이트하는 것을 권장합니다. 새 버전은 자동 모드 감지와 같은 강력한 새 기능을 추가하면서 설정을 간소화합니다.

필수 변경 사항

모든 베타 사용자는 업그레이드를 위해 워크플로 파일에 다음 변경 사항을 적용해야 합니다:

1. Action 버전 업데이트: @beta를 @v1으로 변경
2. 모드 설정 제거: mode: "tag" 또는 mode: "agent" 삭제 (이제 자동 감지됨)
3. 프롬프트 입력 업데이트: direct_prompt를 prompt로 교체
4. CLI 옵션 이동: max_turns, model, custom_instructions 등을 claude_args로 전환

주요 변경 사항 참조

전후 비교 예시

베타 버전:

- 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-6"

GA 버전 (v1.0):

- 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-6

팁:

이제 Action은 설정에 따라 대화형 모드(@claude 멘션에 응답)로 실행할지 자동화 모드(프롬프트와 함께 즉시 실행)로 실행할지 자동으로 감지합니다.

사용 예시

Claude Code GitHub Actions는 다양한 작업에 도움을 줄 수 있습니다. examples 디렉토리에는 다양한 시나리오에 바로 사용할 수 있는 워크플로가 포함되어 있습니다.

기본 워크플로

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 }}
          # Responds to @claude mentions in comments

스킬 사용하기

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: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model opus"

일반적인 사용 사례

이슈나 PR 댓글에서:

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

Claude는 자동으로 컨텍스트를 분석하고 적절하게 응답합니다.

모범 사례

CLAUDE.md 설정

저장소 루트에 CLAUDE.md 파일을 생성하여 코드 스타일 가이드라인, 리뷰 기준, 프로젝트별 규칙, 선호 패턴을 정의하세요. 이 파일은 프로젝트 표준에 대한 Claude의 이해를 안내합니다.

보안 고려사항

주의:

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

권한, 인증, 모범 사례를 포함한 포괄적인 보안 가이드는 Claude Code Action 보안 문서를 참조하세요.

API 키에는 항상 GitHub Secrets를 사용하세요:

• API 키를 ANTHROPIC_API_KEY라는 이름의 저장소 시크릿으로 추가하세요
• 워크플로에서 참조하세요: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
• Action 권한을 필요한 최소한으로 제한하세요
• 병합 전에 Claude의 제안을 검토하세요

워크플로 파일에 API 키를 직접 하드코딩하지 말고, 항상 GitHub Secrets(예: ${{ secrets.ANTHROPIC_API_KEY }})를 사용하세요.

성능 최적화

이슈 템플릿을 사용하여 컨텍스트를 제공하고, CLAUDE.md를 간결하고 집중적으로 유지하며, 워크플로에 적절한 타임아웃을 설정하세요.

CI 비용

Claude Code GitHub Actions를 사용할 때 관련 비용에 유의하세요:

GitHub Actions 비용

• Claude Code는 GitHub 호스팅 러너에서 실행되며, GitHub Actions 분 단위 사용량을 소비합니다
• 자세한 가격 및 분 단위 제한에 대해서는 GitHub 과금 문서를 참조하세요

API 비용

• 각 Claude 상호작용은 프롬프트와 응답의 길이에 따라 API 토큰을 소비합니다
• 토큰 사용량은 작업 복잡도와 코드베이스 크기에 따라 달라집니다
• 현재 토큰 요금은 Claude 가격 페이지를 참조하세요

비용 최적화 팁

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

설정 예시

Claude Code Action v1은 통합된 파라미터로 설정을 간소화합니다:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Your instructions here" # Optional
    claude_args: "--max-turns 5" # Optional CLI arguments

주요 기능:

• 통합 프롬프트 인터페이스 - 모든 지시사항에 prompt를 사용
• 명령어 - /review나 /fix 같은 사전 구축된 프롬프트
• CLI 전달 - claude_args를 통해 모든 Claude Code CLI 인자 전달 가능
• 유연한 트리거 - 모든 GitHub 이벤트와 호환

전체 워크플로 파일은 examples 디렉토리를 방문하세요.

팁:

이슈나 PR 댓글에 응답할 때, Claude는 자동으로 @claude 멘션에 응답합니다. 다른 이벤트의 경우 prompt 파라미터를 사용하여 지시사항을 제공하세요.

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

엔터프라이즈 환경에서는 자체 클라우드 인프라와 함께 Claude Code GitHub Actions를 사용할 수 있습니다. 이 접근 방식을 통해 동일한 기능을 유지하면서 데이터 상주 위치와 과금을 제어할 수 있습니다.

사전 요구사항

클라우드 제공업체와 함께 Claude Code GitHub Actions를 설정하기 전에 다음이 필요합니다:

Google Cloud Vertex AI의 경우:

1. Vertex AI가 활성화된 Google Cloud 프로젝트
2. GitHub Actions용으로 구성된 Workload Identity Federation
3. 필요한 권한이 있는 서비스 계정
4. GitHub App (권장) 또는 기본 GITHUB_TOKEN 사용

AWS Bedrock의 경우:

1. Amazon Bedrock이 활성화된 AWS 계정
2. AWS에 구성된 GitHub OIDC Identity Provider
3. Bedrock 권한이 있는 IAM 역할
4. GitHub App (권장) 또는 기본 GITHUB_TOKEN 사용

Step 1: 커스텀 GitHub App 생성 (서드파티 제공업체에 권장)

Vertex AI나 Bedrock 같은 서드파티 제공업체 사용 시 최상의 제어와 보안을 위해 자체 GitHub App을 생성하는 것을 권장합니다:

1. https://github.com/settings/apps/new로 이동
2. 기본 정보를 입력:
   • GitHub App name: 고유한 이름 선택 (예: "YourOrg Claude Assistant")
   • Homepage URL: 조직의 웹사이트 또는 저장소 URL
3. 앱 설정을 구성:
   • Webhooks: "Active" 체크 해제 (이 통합에는 필요하지 않음)
4. 필요한 권한을 설정:
   • Repository permissions:
     • Contents: Read & Write
     • Issues: Read & Write
     • Pull requests: Read & Write
5. "Create GitHub App" 클릭
6. 생성 후 "Generate a private key"를 클릭하고 다운로드된 .pem 파일을 저장
7. 앱 설정 페이지에서 App ID를 기록
8. 저장소에 앱을 설치:
   • 앱 설정 페이지에서 왼쪽 사이드바의 "Install App" 클릭
   • 계정 또는 조직 선택
   • "Only select repositories"를 선택하고 특정 저장소 선택
   • "Install" 클릭
9. 저장소에 시크릿으로 프라이빗 키를 추가:
   • 저장소의 Settings → Secrets and variables → Actions로 이동
   • .pem 파일의 내용으로 APP_PRIVATE_KEY라는 새 시크릿 생성
10. 시크릿으로 App ID를 추가:

• GitHub App의 ID로 APP_ID라는 새 시크릿 생성

참고:

이 앱은 워크플로에서 인증 토큰을 생성하기 위해 actions/create-github-app-token Action과 함께 사용됩니다.

Claude API 사용자 또는 자체 Github 앱을 설정하고 싶지 않은 경우의 대안: 공식 Anthropic 앱을 사용하세요:

1. 다음에서 설치: https://github.com/apps/claude
2. 인증을 위한 추가 설정이 필요하지 않습니다

Step 2: 클라우드 제공업체 인증 구성

클라우드 제공업체를 선택하고 안전한 인증을 설정하세요:

Step 3: 필수 시크릿 추가

저장소에 다음 시크릿을 추가하세요 (Settings → Secrets and variables → Actions):

Claude API (직접) 사용 시:

1. API 인증용:

   • ANTHROPIC_API_KEY: console.anthropic.com에서 발급받은 Claude API 키

2. GitHub App용 (자체 앱 사용 시):

   • APP_ID: GitHub App의 ID
   • APP_PRIVATE_KEY: 프라이빗 키 (.pem) 내용

Google Cloud Vertex AI 사용 시

1. GCP 인증용:

   • GCP_WORKLOAD_IDENTITY_PROVIDER
   • GCP_SERVICE_ACCOUNT

2. GitHub App용 (자체 앱 사용 시):

   • APP_ID: GitHub App의 ID
   • APP_PRIVATE_KEY: 프라이빗 키 (.pem) 내용

AWS Bedrock 사용 시

1. AWS 인증용:

   • AWS_ROLE_TO_ASSUME

2. GitHub App용 (자체 앱 사용 시):

   • APP_ID: GitHub App의 ID
   • APP_PRIVATE_KEY: 프라이빗 키 (.pem) 내용

Step 4: 워크플로 파일 생성

클라우드 제공업체와 통합하는 GitHub Actions 워크플로 파일을 생성합니다. 아래 예시는 AWS Bedrock과 Google Vertex AI 모두에 대한 전체 설정을 보여줍니다:

name: Claude PR Action

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude-pr:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - 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-6 --max-turns 10'

name: Claude PR Action

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude-pr:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - 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:
          github_token: ${{ steps.app-token.outputs.token }}
          trigger_phrase: "@claude"
          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
          VERTEX_REGION_CLAUDE_3_7_SONNET: us-east5

문제 해결

Claude가 @claude 명령에 응답하지 않는 경우

GitHub App이 올바르게 설치되었는지 확인하고, 워크플로가 활성화되어 있는지 확인하고, API 키가 저장소 시크릿에 설정되어 있는지 확인하고, 댓글에 @claude(/claude가 아님)가 포함되어 있는지 확인하세요.

Claude의 커밋에서 CI가 실행되지 않는 경우

GitHub App 또는 커스텀 앱(Actions 사용자가 아닌)을 사용하고 있는지 확인하고, 워크플로 트리거에 필요한 이벤트가 포함되어 있는지 확인하고, 앱 권한에 CI 트리거가 포함되어 있는지 확인하세요.

인증 오류

API 키가 유효하고 충분한 권한이 있는지 확인하세요. Bedrock/Vertex의 경우 자격 증명 설정을 확인하고 워크플로에서 시크릿 이름이 올바른지 확인하세요.

고급 설정

Action 파라미터

Claude Code Action v1은 간소화된 설정을 사용합니다:

*prompt는 선택사항입니다 - 이슈/PR 댓글에서 생략하면, Claude가 트리거 구문에 응답합니다
**Claude API 직접 사용 시 필수, Bedrock/Vertex에서는 불필요

CLI 인자 전달

claude_args 파라미터는 모든 Claude Code CLI 인자를 허용합니다:

claude_args: "--max-turns 5 --model claude-sonnet-4-6 --mcp-config /path/to/config.json"

주요 인자:

• --max-turns: 최대 대화 턴 수 (기본값: 10)
• --model: 사용할 모델 (예: claude-sonnet-4-6)
• --mcp-config: MCP 설정 경로
• --allowed-tools: 허용된 도구의 쉼표 구분 목록
• --debug: 디버그 출력 활성화

대체 통합 방법

/install-github-app 명령이 권장되는 접근 방식이지만, 다음과 같은 방법도 사용할 수 있습니다:

• 커스텀 GitHub App: 브랜드 사용자 이름이나 커스텀 인증 흐름이 필요한 조직용. 필요한 권한(contents, issues, pull requests)으로 자체 GitHub App을 생성하고, actions/create-github-app-token Action을 사용하여 워크플로에서 토큰을 생성하세요.
• 수동 GitHub Actions: 최대 유연성을 위한 직접 워크플로 설정
• MCP 설정: Model Context Protocol 서버의 동적 로딩

인증, 보안, 고급 설정에 대한 자세한 가이드는 Claude Code Action 문서를 참조하세요.

Claude의 동작 커스터마이징

Claude의 동작을 두 가지 방식으로 설정할 수 있습니다:

1. CLAUDE.md: 저장소 루트에 CLAUDE.md 파일을 만들어 코딩 표준, 리뷰 기준, 프로젝트별 규칙을 정의하세요. Claude는 PR을 생성하고 요청에 응답할 때 이 가이드라인을 따릅니다. 자세한 내용은 메모리 문서를 확인하세요.
2. 커스텀 프롬프트: 워크플로 파일에서 prompt 파라미터를 사용하여 워크플로별 지시사항을 제공하세요. 이를 통해 다양한 워크플로나 작업에 맞게 Claude의 동작을 커스터마이징할 수 있습니다.

Claude는 PR을 생성하고 요청에 응답할 때 이 가이드라인을 따릅니다.