GitHub Actions - Anthropic

Claude Code GitHub Actions는 GitHub 워크플로우에 AI 기반 자동화를 제공합니다. PR이나 이슈에서 간단한 @claude 멘션만으로 Claude가 코드를 분석하고, 풀 리퀘스트를 생성하며, 기능을 구현하고, 버그를 수정할 수 있습니다 - 모두 프로젝트 표준을 준수하면서 말이죠.

Claude Code GitHub Actions는 현재 베타 버전입니다. 경험을 개선하면서 기능과 작동 방식이 발전할 수 있습니다.

Claude Code GitHub Actions는 Claude Code SDK 위에 구축되었으며, 이를 통해 Claude Code를 애플리케이션에 프로그래밍 방식으로 통합할 수 있습니다. SDK를 사용하여 GitHub Actions 외에도 사용자 정의 자동화 워크플로우를 구축할 수 있습니다.

Claude Code GitHub Actions를 사용하는 이유?

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

Claude가 할 수 있는 일은 무엇인가요?

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

Claude Code Action

이 GitHub Action을 사용하면 GitHub Actions 워크플로우 내에서 Claude Code를 실행할 수 있습니다. 이를 통해 Claude Code 위에 사용자 정의 워크플로우를 구축할 수 있습니다.

저장소 보기 →

Claude Code Action (Base)

Claude로 사용자 정의 GitHub 워크플로우를 구축하기 위한 기반입니다. 이 확장 가능한 프레임워크는 맞춤형 자동화를 만들기 위한 Claude의 기능에 완전한 접근을 제공합니다.

저장소 보기 →

빠른 시작

이 액션을 설정하는 가장 쉬운 방법은 터미널에서 Claude Code를 통하는 것입니다. claude를 열고 /install-github-app을 실행하기만 하면 됩니다.

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

GitHub 앱을 설치하고 시크릿을 추가하려면 저장소 관리자여야 합니다
이 빠른 시작 방법은 Anthropic API 직접 사용자만 이용할 수 있습니다. AWS Bedrock 또는 Google Vertex AI를 사용하는 경우 AWS Bedrock 및 Google Vertex AI와 함께 사용하기 섹션을 참조하세요.

설정 스크립트가 실패하는 경우

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

Claude GitHub 앱을 저장소에 설치하세요: https://github.com/apps/claude
ANTHROPIC_API_KEY를 저장소 시크릿에 추가하세요 (GitHub Actions에서 시크릿을 사용하는 방법 알아보기)
워크플로우 파일을 examples/claude.yml에서 저장소의 .github/workflows/로 복사하세요

액션 테스트

빠른 시작 또는 수동 설정을 완료한 후, 이슈나 PR 댓글에서 @claude를 태그하여 액션을 테스트하세요!

사용 사례 예시

Claude Code GitHub Actions는 다양한 작업을 도울 수 있습니다. 완전한 작동 예시는 examples 디렉토리를 참조하세요.

이슈를 PR로 전환

# In an issue comment:
@claude implement this feature based on the issue description

Claude는 이슈를 분석하고, 코드를 작성하고, 검토를 위한 PR을 생성합니다.

구현 도움 받기

# In a PR comment:
@claude how should I implement user authentication for this endpoint?

Claude는 코드를 분석하고 구체적인 구현 지침을 제공합니다.

버그 빠르게 수정

# In an issue:
@claude fix the TypeError in the user dashboard component

Claude는 버그를 찾고, 수정을 구현하고, PR을 생성합니다.

모범 사례

CLAUDE.md 구성

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

보안 고려 사항

⚠️ 중요: API 키를 절대 저장소에 직접 커밋하지 마세요!

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

API 키를 ANTHROPIC_API_KEY라는 이름의 저장소 시크릿으로 추가하세요
워크플로우에서 참조하세요: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
액션 권한을 필요한 것으로만 제한하세요
병합하기 전에 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 명령을 사용하세요
과도한 반복을 방지하기 위해 적절한 max_turns 제한을 구성하세요
런어웨이 워크플로우를 방지하기 위해 합리적인 timeout_minutes를 설정하세요
병렬 실행을 제한하기 위해 GitHub의 동시성 제어 사용을 고려하세요

구성 예시

다음을 포함한 다양한 사용 사례에 대한 즉시 사용 가능한 워크플로우 구성:

이슈 및 PR 댓글에 대한 기본 워크플로우 설정
풀 리퀘스트에 대한 자동화된 코드 리뷰
특정 요구 사항에 대한 사용자 정의 구현

Claude Code Action 저장소의 examples 디렉토리를 방문하세요.

예제 저장소에는 .github/workflows/ 디렉토리에 직접 복사할 수 있는 완전하고 테스트된 워크플로우가 포함되어 있습니다.

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

기업 환경의 경우, 자체 클라우드 인프라와 함께 Claude Code GitHub Actions를 사용할 수 있습니다. 이 접근 방식은 동일한 기능을 유지하면서 데이터 상주 및 결제에 대한 제어 권한을 제공합니다.

전제 조건

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

Google Cloud Vertex AI의 경우:

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

AWS Bedrock의 경우:

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

사용자 정의 GitHub 앱 생성 (3P 제공업체에 권장)

Vertex AI나 Bedrock과 같은 3P 제공업체를 사용할 때 최상의 제어와 보안을 위해 자체 GitHub 앱을 생성하는 것이 좋습니다:

https://github.com/settings/apps/new로 이동하세요
기본 정보를 입력하세요:
- GitHub 앱 이름: 고유한 이름 선택 (예: “YourOrg Claude Assistant”)
- 홈페이지 URL: 조직의 웹사이트 또는 저장소 URL
앱 설정 구성:
- 웹훅: “활성” 체크 해제 (이 통합에는 필요하지 않음)
필요한 권한 설정:
- 저장소 권한:
  - Contents: 읽기 및 쓰기
  - Issues: 읽기 및 쓰기
  - Pull requests: 읽기 및 쓰기
“GitHub 앱 생성” 클릭
생성 후, “프라이빗 키 생성”을 클릭하고 다운로드된 .pem 파일 저장
앱 설정 페이지에서 앱 ID 기록
앱을 저장소에 설치:
- 앱 설정 페이지에서 왼쪽 사이드바의 “앱 설치”를 클릭
- 계정 또는 조직 선택
- “특정 저장소만 선택”을 선택하고 특정 저장소 선택
- “설치” 클릭
프라이빗 키를 저장소 시크릿으로 추가:
- 저장소의 Settings → Secrets and variables → Actions로 이동
- .pem 파일의 내용으로 APP_PRIVATE_KEY라는 새 시크릿 생성
앱 ID를 시크릿으로 추가:

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

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

Anthropic API를 사용하거나 자체 Github 앱을 설정하지 않으려는 경우 대안: 공식 Anthropic 앱 사용:

다음에서 설치: https://github.com/apps/claude
인증에 필요한 추가 구성 없음

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

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

AWS Bedrock

Google Vertex AI

필요한 시크릿 추가

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

Anthropic API (직접)의 경우:

API 인증용:
- ANTHROPIC_API_KEY: console.anthropic.com에서 가져온 Anthropic API 키
GitHub 앱용 (자체 앱을 사용하는 경우):
- APP_ID: GitHub 앱 ID
- APP_PRIVATE_KEY: 프라이빗 키(.pem) 내용

Google Cloud Vertex AI의 경우

GCP 인증용:
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
GitHub 앱용 (자체 앱을 사용하는 경우):
- APP_ID: GitHub 앱 ID
- APP_PRIVATE_KEY: 프라이빗 키(.pem) 내용

AWS Bedrock의 경우

AWS 인증용:
- AWS_ROLE_TO_ASSUME
GitHub 앱용 (자체 앱을 사용하는 경우):
- APP_ID: GitHub 앱 ID
- APP_PRIVATE_KEY: 프라이빗 키(.pem) 내용

워크플로우 파일 생성

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

AWS Bedrock 워크플로우

전제 조건:

Claude 모델 권한이 있는 AWS Bedrock 액세스 활성화
AWS에서 OIDC ID 제공자로 구성된 GitHub
GitHub Actions를 신뢰하는 Bedrock 권한이 있는 IAM 역할

필요한 GitHub 시크릿:

시크릿 이름	설명
`AWS_ROLE_TO_ASSUME`	Bedrock 액세스를 위한 IAM 역할의 ARN
`APP_ID`	GitHub 앱 ID (앱 설정에서)
`APP_PRIVATE_KEY`	GitHub 앱용으로 생성한 프라이빗 키

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: ./.github/actions/claude-pr-action
        with:
          trigger_phrase: "@claude"
          timeout_minutes: "60"
          github_token: ${{ steps.app-token.outputs.token }}
          use_bedrock: "true"
          model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"

Bedrock의 모델 ID 형식에는 지역 접두사(예: us.anthropic.claude...)와 버전 접미사가 포함됩니다.

Google Vertex AI 워크플로우

전제 조건:

GCP 프로젝트에서 활성화된 Vertex AI API
GitHub용으로 구성된 Workload Identity Federation
Vertex AI 권한이 있는 서비스 계정

필요한 GitHub 시크릿:

시크릿 이름	설명
`GCP_WORKLOAD_IDENTITY_PROVIDER`	Workload identity 제공자 리소스 이름
`GCP_SERVICE_ACCOUNT`	Vertex AI 액세스가 있는 서비스 계정 이메일
`APP_ID`	GitHub 앱 ID (앱 설정에서)
`APP_PRIVATE_KEY`	GitHub 앱용으로 생성한 프라이빗 키

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: ./.github/actions/claude-pr-action
        with:
          trigger_phrase: "@claude"
          timeout_minutes: "60"
          github_token: ${{ steps.app-token.outputs.token }}
          use_vertex: "true"
          model: "claude-3-7-sonnet@20250219"
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5
          VERTEX_REGION_CLAUDE_3_7_SONNET: us-east5

프로젝트 ID는 Google Cloud 인증 단계에서 자동으로 검색되므로 하드코딩할 필요가 없습니다.

문제 해결

Claude가 @claude 명령에 응답하지 않음

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

Claude의 커밋에서 CI가 실행되지 않음

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

인증 오류

API 키가 유효하고 충분한 권한이 있는지 확인하세요. Bedrock/Vertex의 경우, 자격 증명 구성을 확인하고 시크릿이 워크플로우에서 올바르게 명명되었는지 확인하세요.

고급 구성

액션 매개변수

Claude Code Action은 다음과 같은 주요 매개변수를 지원합니다:

매개변수	설명	필수
`prompt`	Claude에게 보낼 프롬프트	예*
`prompt_file`	프롬프트가 포함된 파일 경로	예*
`anthropic_api_key`	Anthropic API 키	예**
`max_turns`	최대 대화 턴 수	아니오
`timeout_minutes`	실행 타임아웃	아니오

*prompt 또는 prompt_file 중 하나 필요
**직접 Anthropic API에는 필요하지만 Bedrock/Vertex에는 필요하지 않음

대체 통합 방법

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

사용자 정의 GitHub 앱: 브랜드 사용자 이름이나 사용자 정의 인증 흐름이 필요한 조직을 위한 것입니다. 필요한 권한(콘텐츠, 이슈, 풀 리퀘스트)이 있는 자체 GitHub 앱을 만들고 actions/create-github-app-token 액션을 사용하여 워크플로우에서 토큰을 생성하세요.
수동 GitHub Actions: 최대 유연성을 위한 직접 워크플로우 구성
MCP 구성: Model Context Protocol 서버의 동적 로딩

자세한 문서는 Claude Code Action 저장소를 참조하세요.

Claude의 동작 사용자 정의

두 가지 방법으로 Claude의 동작을 구성할 수 있습니다:

CLAUDE.md: 저장소 루트에 CLAUDE.md 파일에서 코딩 표준, 리뷰 기준 및 프로젝트별 규칙을 정의하세요. Claude는 PR을 생성하고 요청에 응답할 때 이러한 가이드라인을 따릅니다. 자세한 내용은 Memory 문서를 확인하세요.
사용자 정의 프롬프트: 워크플로우 파일에서 prompt 매개변수를 사용하여 워크플로우별 지침을 제공하세요. 이를 통해 다양한 워크플로우나 작업에 대해 Claude의 동작을 사용자 정의할 수 있습니다.

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

Claude Code

​Claude Code GitHub Actions를 사용하는 이유?

​Claude가 할 수 있는 일은 무엇인가요?

​Claude Code Action

​Claude Code Action (Base)

​빠른 시작

​설정 스크립트가 실패하는 경우

​사용 사례 예시

​이슈를 PR로 전환

​구현 도움 받기

​버그 빠르게 수정

​모범 사례

​CLAUDE.md 구성

​보안 고려 사항

​성능 최적화

​CI 비용

​구성 예시

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

​전제 조건

​Google Cloud Vertex AI의 경우:

​AWS Bedrock의 경우:

​Anthropic API (직접)의 경우:

​Google Cloud Vertex AI의 경우

​AWS Bedrock의 경우

​문제 해결

​Claude가 @claude 명령에 응답하지 않음

​Claude의 커밋에서 CI가 실행되지 않음

​인증 오류

​고급 구성

​액션 매개변수

​대체 통합 방법

​Claude의 동작 사용자 정의

Claude Code GitHub Actions를 사용하는 이유?

Claude가 할 수 있는 일은 무엇인가요?

Claude Code Action

Claude Code Action (Base)

빠른 시작

설정 스크립트가 실패하는 경우

사용 사례 예시

이슈를 PR로 전환

구현 도움 받기

버그 빠르게 수정

모범 사례

CLAUDE.md 구성

보안 고려 사항

성능 최적화

CI 비용

구성 예시

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

전제 조건

Google Cloud Vertex AI의 경우:

AWS Bedrock의 경우:

Anthropic API (직접)의 경우:

Google Cloud Vertex AI의 경우

AWS Bedrock의 경우

문제 해결

Claude가 @claude 명령에 응답하지 않음

Claude의 커밋에서 CI가 실행되지 않음

인증 오류

고급 구성

액션 매개변수

대체 통합 방법

Claude의 동작 사용자 정의