GitHub Actions 통합 가이드
Claude Code를 GitHub Actions와 통합하여 PR과 이슈에서 AI 기반 자동화를 구현하는 완전한 가이드입니다.
🚀 빠른 시작
⚡ Claude Code CLI를 사용한 자동 설정 (권장)
가장 쉬운 방법은 Claude Code CLI를 사용하는 것입니다:
claude/install-github-app이 명령어는 GitHub 앱 설치와 필요한 시크릿 설정을 자동으로 안내합니다.
⚠️ 요구사항
- • 저장소 관리자 권한 필요
- • Anthropic API 직접 사용자만 가능 (AWS Bedrock 사용자는 수동 설정 필요)
⚙️ 수동 설정
2. API 키 시크릿 추가
저장소 설정에서 ANTHROPIC_API_KEY 시크릿을 추가합니다:
- 저장소 → Settings → Secrets and variables → Actions
- "New repository secret" 클릭
- Name:
ANTHROPIC_API_KEY - Value: 여러분의 Anthropic API 키
- "Add secret" 클릭
3. 워크플로우 파일 생성
.github/workflows/claude.yml 파일을 생성합니다:
name: Claude Assistant
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]
pull_request_review:
types: [submitted]
jobs:
claude-response:
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}💬 기본 사용법
📋 질문하기
PR이나 이슈에 댓글을 추가하세요:
@claude 이 함수가 무엇을 하는지 설명해주세요🔧 수정 요청
구체적인 변경사항을 요청하세요:
@claude 이 함수에 에러 처리를 추가해주세요🔍 코드 리뷰
포괄적인 리뷰를 요청하세요:
@claude 이 PR을 리뷰하고 개선사항을 제안해주세요🐛 버그 수정
스크린샷과 함께 버그를 신고하세요:
@claude 이 스크린샷의 버그를 수정해주세요 [이미지 첨부]🔧 고급 설정
커스텀 도구 허용
기본적으로 Claude는 파일 작업과 GitHub 작업만 수행할 수 있습니다. 추가 명령어를 허용하려면:
- uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
allowed_tools: "Bash(npm install),Bash(npm test),Bash(pnpm build)"
disallowed_tools: "TaskOutput,KillTask"환경 변수 설정
테스트나 빌드를 위한 환경 변수를 설정할 수 있습니다:
- uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_env: |
NODE_ENV: test
CI: true
DATABASE_URL: postgres://test:test@localhost:5432/test_db커스텀 트리거 설정
기본 @claude 대신 다른 트리거를 사용할 수 있습니다:
- uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
trigger_phrase: "/claude"
assignee_trigger: "claude-bot"🤖 자동화 예제
자동 문서 업데이트
API 파일이 변경될 때 자동으로 문서를 업데이트합니다:
name: Auto Documentation Update
on:
pull_request:
paths:
- "src/api/**/*.ts"
jobs:
update-docs:
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
direct_prompt: |
README.md의 API 문서를 이 PR의 API 엔드포인트
변경사항에 맞게 업데이트해주세요.특정 작성자 PR 자동 리뷰
외부 기여자나 특정 개발자의 PR을 자동으로 리뷰합니다:
name: Auto Review External PRs
on:
pull_request:
types: [opened, synchronize]
jobs:
review-external:
if: |
github.event.pull_request.user.login == 'external-contributor' ||
github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
direct_prompt: |
이 PR을 철저히 리뷰해주세요. 외부 기여자의 코드이므로
코딩 표준, 보안 관행, 테스트 커버리지에 특별히 주의해주세요.🔒 보안 설정
⚠️ 중요: API 키 보안
절대로 API 키를 워크플로우 파일에 직접 작성하지 마세요!
✅ 올바른 방법:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}❌ 잘못된 방법:
anthropic_api_key: "sk-ant-api03-..."접근 제어
- • 저장소 쓰기 권한이 있는 사용자만 트리거 가능
- • GitHub 앱과 봇은 액션을 트리거할 수 없음
- • 단기간 토큰만 사용
- • 저장소별로 범위 제한
GitHub 앱 권한
- • Pull Requests: 읽기/쓰기
- • Issues: 읽기/쓰기
- • Contents: 읽기/쓰기
- • 자동 커밋 서명
🐛 트러블슈팅
Q: Claude가 댓글에 응답하지 않아요
확인사항:
- GitHub 앱이 설치되어 있는지 확인
- ANTHROPIC_API_KEY 시크릿이 설정되어 있는지 확인
- 워크플로우 파일이 올바른 위치(.github/workflows/)에 있는지 확인
- 트리거 문구(@claude)를 정확히 사용했는지 확인
- 저장소에 쓰기 권한이 있는지 확인
Q: API 키 관련 오류가 발생해요
해결방법:
- API 키가 올바른 형식(sk-ant-로 시작)인지 확인
- 시크릿 이름이 정확히 ANTHROPIC_API_KEY인지 확인
- API 키가 만료되지 않았는지 확인
- Anthropic 계정에 충분한 크레딧이 있는지 확인
Q: Claude가 특정 명령어를 실행할 수 없어요
해결방법:
- allowed_tools 설정에 해당 명령어가 포함되어 있는지 확인
- 예:
allowed_tools: "Bash(npm install),Bash(npm test)" - 보안상 기본적으로 파일 작업과 GitHub 작업만 허용됨