Claude Code GitHub Actions
Claude Code GitHub Actions를 사용하여 개발 워크플로우에 Claude Code를 통합하는 방법을 알아보세요
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로 변환
이슈 댓글에서:
Claude가 이슈를 분석하고, 코드를 작성하며, 검토를 위한 PR을 생성합니다.
구현 도움 받기
PR 댓글에서:
Claude가 코드를 분석하고 구체적인 구현 가이드를 제공합니다.
버그 빠르게 수정
이슈에서:
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 디렉토리를 방문하세요.
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 App name: 고유한 이름 선택 (예: “YourOrg Claude Assistant”)
- Homepage URL: 조직의 웹사이트 또는 저장소 URL
- 앱 설정 구성:
- Webhooks: “Active” 체크 해제 (이 통합에는 필요하지 않음)
- 필요한 권한 설정:
- Repository permissions:
- Contents: Read & Write
- Issues: Read & Write
- Pull requests: Read & Write
- Repository permissions:
- “Create GitHub App” 클릭
- 생성 후 “Generate a private key”를 클릭하고 다운로드된
.pem
파일을 저장 - 앱 설정 페이지에서 App ID를 기록
- 저장소에 앱 설치:
- 앱의 설정 페이지에서 왼쪽 사이드바의 “Install App” 클릭
- 계정 또는 조직 선택
- “Only select repositories”를 선택하고 특정 저장소 선택
- “Install” 클릭
- 개인 키를 저장소의 시크릿으로 추가:
- 저장소의 Settings → Secrets and variables → Actions로 이동
.pem
파일의 내용으로APP_PRIVATE_KEY
라는 새 시크릿 생성
- App ID를 시크릿으로 추가:
- GitHub 앱의 ID로
APP_ID
라는 새 시크릿 생성
이 앱은 워크플로우에서 인증 토큰을 생성하기 위해 actions/create-github-app-token 액션과 함께 사용됩니다.
Anthropic API 또는 자체 Github 앱을 설정하고 싶지 않은 경우의 대안: 공식 Anthropic 앱 사용:
- https://github.com/apps/claude에서 설치
- 인증을 위한 추가 구성 필요 없음
클라우드 제공업체 인증 구성
클라우드 제공업체를 선택하고 보안 인증을 설정하세요:
필요한 시크릿 추가
저장소에 다음 시크릿을 추가하세요 (Settings → Secrets and variables → Actions):
Anthropic API (직접)의 경우:
-
API 인증용:
ANTHROPIC_API_KEY
: console.anthropic.com의 Anthropic API 키
-
GitHub 앱용 (자체 앱을 사용하는 경우):
APP_ID
: GitHub 앱의 IDAPP_PRIVATE_KEY
: 개인 키 (.pem) 내용
Google Cloud Vertex AI의 경우
-
GCP 인증용:
GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT
-
GitHub 앱용 (자체 앱을 사용하는 경우):
APP_ID
: GitHub 앱의 IDAPP_PRIVATE_KEY
: 개인 키 (.pem) 내용
AWS Bedrock의 경우
-
AWS 인증용:
AWS_ROLE_TO_ASSUME
-
GitHub 앱용 (자체 앱을 사용하는 경우):
APP_ID
: GitHub 앱의 IDAPP_PRIVATE_KEY
: 개인 키 (.pem) 내용
워크플로우 파일 생성
클라우드 제공업체와 통합되는 GitHub Actions 워크플로우 파일을 생성하세요. 아래 예시는 AWS Bedrock과 Google Vertex AI 모두에 대한 완전한 구성을 보여줍니다:
문제 해결
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 앱: 브랜드 사용자 이름이나 사용자 정의 인증 플로우가 필요한 조직용. 필요한 권한(contents, issues, pull requests)으로 자체 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을 생성하고 요청에 응답할 때 이러한 가이드라인을 따릅니다.