[Claude Code 번역] Claude Code GitHub Actions (Claude Code GitHub Actions)

출처: https://docs.anthropic.com/en/docs/claude-code/github-actions

개요

Claude Code GitHub Actions를 사용하면 자동화된 코드 리뷰, PR 관리, 이슈 분류 등 GitHub 워크플로우에 AI 기반 자동화를 통합할 수 있습니다.

간단히 PR이나 이슈에서 @claude를 멘션하면 Claude가 코드를 분석하고, 풀 리퀘스트를 생성하며, 기능을 구현하고, 버그를 수정합니다. 이 모든 과정에서 프로젝트의 표준을 준수합니다.

Claude Code GitHub Actions는 현재 베타 버전입니다. 기능과 사용성은 지속적으로 개선될 수 있습니다.

Claude Code GitHub Actions는 Claude Code SDK 위에 구축되어 있어, 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을 사용하면 Claude Code를 GitHub Actions 워크플로우 내에서 실행할 수 있습니다. 이를 통해 다양한 맞춤형 워크플로우를 구축할 수 있습니다.

Claude Code Action (Base)

맞춤형 GitHub 워크플로우 구축을 위한 기반이 되는 확장 가능한 프레임워크로, Claude의 모든 기능을 활용할 수 있습니다.

빠른 시작

가장 쉬운 설정 방법은 터미널에서 Claude Code를 실행한 후 /install-github-app 명령을 입력하는 것입니다.

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

저장소 관리 권한이 필요합니다.
이 방법은 Anthropic API를 직접 사용하는 경우에만 가능합니다. AWS Bedrock 또는 Google Vertex AI를 사용하는 경우, 아래의 별도 안내를 참고하세요.

설치 스크립트 실패 시

/install-github-app 명령이 실패하거나 수동 설정을 원한다면 다음 절차를 따르세요:

Claude GitHub 앱을 저장소에 설치합니다.
저장소 시크릿에 ANTHROPIC_API_KEY를 추가합니다. (GitHub Actions에서 시크릿 사용법 참고)
예시 워크플로우 파일(examples/claude.yml)을 저장소의 .github/workflows/에 복사합니다.

동작 테스트

빠른 시작 또는 수동 설정을 완료한 후, 이슈나 PR 댓글에서 @claude를 멘션하여 동작을 확인할 수 있습니다!

예시 사용 사례

이슈를 PR로 전환

# 이슈 댓글에서:
@claude implement this feature based on the issue description

Claude가 이슈를 분석하고, 코드를 작성하여 PR을 생성합니다.

구현 도움 받기

# PR 댓글에서:
@claude how should I implement user authentication for this endpoint?

Claude가 코드를 분석하고 구체적인 구현 가이드를 제공합니다.

버그 빠르게 수정

# 이슈에서:
@claude fix the TypeError in the user dashboard component

Claude가 버그를 찾아 수정하고 PR을 생성합니다.

베스트 프랙티스

CLAUDE.md 구성

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

보안 고려사항

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

API 키는 반드시 GitHub Secrets로 추가하세요.
예시:

# ✅ 올바른 예시 - GitHub 시크릿 사용
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# ❌ 잘못된 예시 - API 키 노출
anthropic_api_key: "sk-ant-..."

더 나은 보안을 위해 명시적 도구만 허용하세요:

# ✅ 권장 - 명시적 명령만 허용
allowed_tools: "Bash(git status),Bash(git log),Bash(git diff),View,GlobTool"

# ❌ 덜 안전함 - 모든 git 명령 허용
allowed_tools: "Bash(git:*),View,GlobTool"

이렇게 하면 Claude가 허가된 명령만 실행할 수 있어 보안 위험을 줄일 수 있습니다.

성능 최적화

이슈 템플릿을 활용해 충분한 맥락을 제공하세요.
CLAUDE.md는 간결하고 핵심만 담으세요.
워크플로우에 적절한 타임아웃을 설정하세요.

CI 비용

Claude Code는 GitHub 호스팅 러너에서 실행되며, GitHub Actions 사용량이 청구됩니다.
API 사용량은 프롬프트와 응답 길이에 따라 달라집니다.
자세한 가격 정책은 Claude 요금 안내를 참고하세요.

비용 최적화 팁

구체적인 @claude 명령을 사용해 불필요한 API 호출을 줄이세요.
max_turns를 설정해 과도한 반복을 방지하세요.
적절한 timeout_minutes를 설정해 워크플로우가 무한 반복되지 않도록 하세요.
GitHub의 동시 실행 제한을 활용해 병렬 실행을 제어하세요.

구성 예시

기본 워크플로우 설정

아래는 설치 프로그램이 생성하는 기본 워크플로우 예시입니다. 이 워크플로우는 이슈 및 PR 댓글에서 @claude 멘션을 감지해 동작합니다.

name: Claude PR Creation
on:
  issue_comment:
    types: [created]  # 이슈 또는 PR에 댓글이 달릴 때 트리거

jobs:
  create-pr:
    # 댓글에 @claude가 포함된 경우에만 실행
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@beta
        with:
          # 댓글 내용을 프롬프트로 전달
          prompt: "${{ github.event.comment.body }}"

          # Claude가 사용할 수 있는 도구 지정
          allowed_tools: "Bash(git status),Bash(git log),Bash(git show),Bash(git blame),Bash(git reflog),Bash(git stash list),Bash(git ls-files),Bash(git branch),Bash(git tag),Bash(git diff),View,GlobTool,GrepTool,BatchTool"

          # Anthropic API 키 (GitHub 시크릿 사용)
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

이 워크플로우는 이슈 설명과 이전 댓글의 맥락을 Claude가 이해할 수 있도록 합니다.

PR 코드 리뷰 자동화

아래 워크플로우는 PR이 생성되거나 업데이트될 때 자동으로 코드 리뷰를 수행합니다.

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]  # 새 PR 및 업데이트 시 실행

jobs:
  code-review:
    runs-on: ubuntu-latest
    steps:
      # git diff 작업을 위해 코드 체크아웃
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 정확한 diff를 위해 전체 히스토리 가져오기

      - name: Run Code Review with Claude
        id: code-review
        uses: anthropics/claude-code-action@beta
        with:
          # 리뷰 중점 영역 지정
          prompt: "Review the PR changes. Focus on code quality, potential bugs, and performance issues. Suggest improvements where appropriate."

AWS Bedrock & Google Vertex AI 연동

사전 준비 사항

Google Cloud Vertex AI:

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

AWS Bedrock:

Bedrock 접근 권한 및 Claude 모델 권한 필요
AWS에서 GitHub을 OIDC 신원 제공자로 구성
Bedrock 접근 권한이 있는 IAM 역할 필요

필수 GitHub 시크릿

시크릿 이름	설명
GCP_WORKLOAD_IDENTITY_PROVIDER	Workload identity provider 리소스명
GCP_SERVICE_ACCOUNT	Vertex AI 접근 권한 서비스 계정 이메일
APP_ID	GitHub 앱 ID
APP_PRIVATE_KEY	생성한 GitHub 앱의 개인 키

문제 해결

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

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

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

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

인증 오류

API 키가 유효하고 충분한 권한이 있는지 확인하세요.
Bedrock/Vertex 사용 시 자격 증명 구성이 올바른지, 시크릿 이름이 정확한지 확인하세요.

고급 구성

Action 파라미터

Claude Code Action은 다음 주요 파라미터를 지원합니다:

파라미터	설명	필수 여부
prompt	Claude에 전달할 프롬프트	예*
prompt_file	프롬프트가 담긴 파일 경로	예*
allowed_tools	허용할 도구(콤마로 구분)	아니오
anthropic_api_key	Anthropic API 키	예**
max_turns	최대 대화 반복 횟수	아니오
timeout_minutes	실행 타임아웃	아니오

* prompt 또는 prompt_file 중 하나는 필수
** Anthropic API 직접 사용 시 필수, Bedrock/Vertex 사용 시 불필요

Claude 행동 커스터마이징

Claude의 행동은 두 가지 방식으로 커스터마이징할 수 있습니다:

CLAUDE.md: 저장소 루트에 CLAUDE.md 파일을 생성해 코딩 표준, 리뷰 기준, 프로젝트별 규칙을 정의하세요. Claude는 PR 생성 및 요청 응답 시 이 가이드라인을 따릅니다.
커스텀 프롬프트: 워크플로우 파일의 prompt 파라미터를 사용해 워크플로우별 지침을 전달할 수 있습니다.

Claude는 PR 생성 및 요청 응답 시 이 가이드라인을 따릅니다.

저작자표시 (새창열림)

개요