Claude Code + GitHub 연동 완벽 가이드: PR 자동화부터 CI 코드 리뷰까지
Claude Code는 git과 gh 명령어를 직접 실행할 수 있어서, 코드 작성부터 PR 생성까지 하나의 명령으로 처리할 수 있다. GitHub Actions와 연동하면 PR이 열릴 때마다 Claude가 자동으로 코드 리뷰를 작성한다. 이 가이드는 Claude Code와 GitHub 통합의 핵심 패턴을 단계별로 정리한다.
0단계: gh CLI 설치 및 인증
# macOS
brew install gh
# 인증
gh auth login
# GitHub.com → HTTPS → 브라우저 인증 선택
# 확인
gh auth status
Claude Code는 gh가 설치되어 있으면 자동으로 사용한다. 별도 설정 필요 없음.
1단계: GitHub MCP 서버 설정 (선택, 강력 추천)
MCP를 통해 Claude가 GitHub 데이터를 직접 읽을 수 있다.
// ~/.claude.json 또는 .claude/settings.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
Personal Access Token 생성:
GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
권한: repo, pull_requests, issues (읽기/쓰기)
2단계: 기본 Git + GitHub 워크플로우
기능 구현 → PR 생성까지 한 번에
claude "
feature/user-notification 브랜치 생성해줘.
다음 기능 구현해줘:
- 이메일 알림: 계정 생성 시, 비밀번호 변경 시
- 인앱 알림 뱃지 (읽지 않은 수)
- 알림 설정 페이지 /settings/notifications
구현 후:
1. bun run typecheck 실행 → 에러 수정
2. 변경사항 커밋: 'feat(notifications): add email and in-app notification system'
3. GitHub에 푸시
4. PR 생성:
- 제목: 'feat: 사용자 알림 시스템 추가'
- 본문: 변경 사항 요약, 테스트 방법
"
버그 수정 → 핫픽스 PR
claude "
hotfix/null-check-profile 브랜치 생성.
UserCard.tsx의 user.profile.avatar가 null일 때 발생하는 에러 수정해줘.
수정 후 커밋 + 푸시 + PR (base: main).
"
3단계: 이슈 기반 작업 실행
GitHub 이슈를 바탕으로 작업을 지시할 수 있다. MCP 설정이 있으면 Claude가 이슈를 직접 읽는다.
# MCP 없이
claude "
GitHub 이슈 #42의 내용을 읽어줘 (gh issue view 42).
이슈 요구사항을 구현하고 PR을 만들어줘.
PR 본문에 'Closes #42' 포함해줘.
"
# MCP 있으면 더 직접적으로
claude "
이슈 #42 읽고 구현해줘. PR은 'Closes #42' 포함해서 만들어줘.
"
이슈 생성도 Claude가
claude "
이 버그를 GitHub 이슈로 만들어줘:
- 제목: '[버그] 모바일에서 로그인 버튼 클릭 안 됨'
- 라벨: bug, mobile
- 설명: 재현 방법, 예상 동작, 실제 동작 포함
"
4단계: GitHub Actions + Claude 코드 리뷰 자동화
PR이 열릴 때마다 Claude가 자동으로 코드 리뷰를 남기는 워크플로우:
# .github/workflows/claude-review.yml
name: Claude 코드 리뷰
on:
pull_request:
types: [opened, synchronize]
# 코드 파일만 변경됐을 때 실행
paths:
- 'src/**'
- 'app/**'
- '*.ts'
- '*.tsx'
jobs:
review:
runs-on: ubuntu-latest
permissions:
pull-requests: write
contents: read
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: PR diff 추출
run: |
git diff origin/${{ github.base_ref }}...HEAD \
-- '*.ts' '*.tsx' '*.js' '*.jsx' \
| head -c 20000 > /tmp/pr_diff.txt
echo "Diff size: $(wc -c < /tmp/pr_diff.txt) bytes"
- name: Claude 코드 리뷰 실행
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
pip install anthropic
python3 << 'PYTHON'
import anthropic
import os
client = anthropic.Anthropic()
with open('/tmp/pr_diff.txt', 'r') as f:
diff = f.read()
if not diff.strip():
print("변경된 코드 없음 — 리뷰 건너뜀")
exit(0)
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=2000,
messages=[{
"role": "user",
"content": f"""이 PR의 코드 변경사항을 리뷰해줘.
다음 항목을 중심으로 검토해줘:
1. **보안 이슈**: 인증 우회, 인젝션, 입력값 검증 미흡
2. **논리 오류**: 엣지 케이스, null 처리, 경쟁 조건
3. **에러 처리**: try-catch 누락, 에러 전파
4. **성능**: N+1 쿼리, 불필요한 렌더링, 메모리 누수
5. **코드 품질**: 중복 코드, 과도한 복잡도
GitHub PR 코멘트 형식으로 출력해줘. 마크다운 사용.
이슈 없으면 '✅ 주요 이슈 없음'으로 시작.
PR DIFF:
{diff}"""
}]
)
review_text = response.content[0].text
# 결과를 파일로 저장
with open('/tmp/review.txt', 'w') as f:
f.write(review_text)
print("리뷰 완료")
print(review_text[:500])
PYTHON
- name: PR에 리뷰 코멘트 추가
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr comment ${{ github.event.pull_request.number }} \
--body-file /tmp/review.txt
5단계: 자동화된 이슈 → 코드 파이프라인
이슈가 특정 라벨을 받으면 Claude가 자동으로 구현 시도:
# .github/workflows/auto-implement.yml
name: 자동 구현 (실험적)
on:
issues:
types: [labeled]
jobs:
implement:
# 'auto-implement' 라벨이 붙은 이슈만
if: github.event.label.name == 'auto-implement'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Claude로 이슈 구현
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
npm install -g @anthropic-ai/claude-code
ISSUE_TITLE="${{ github.event.issue.title }}"
ISSUE_BODY="${{ github.event.issue.body }}"
ISSUE_NUMBER="${{ github.event.issue.number }}"
# 브랜치 생성
git checkout -b "auto/issue-${ISSUE_NUMBER}"
git config user.name "Claude Bot"
git config user.email "claude-bot@example.com"
# Claude로 구현
claude --print "
GitHub 이슈 #${ISSUE_NUMBER}를 구현해줘:
제목: ${ISSUE_TITLE}
내용: ${ISSUE_BODY}
구현 후:
- bun run typecheck
- git add -A
- git commit -m 'feat: closes #${ISSUE_NUMBER}'
" --max-turns 20
# 푸시 + PR
git push origin "auto/issue-${ISSUE_NUMBER}"
gh pr create \
--title "feat: ${ISSUE_TITLE}" \
--body "Closes #${ISSUE_NUMBER}\n\nClaude가 자동 생성한 PR입니다. 검토 후 머지해주세요." \
--base main
⚠️ 이 패턴은 실험적이다. 프로덕션에서는 반드시 인간 리뷰 단계를 거쳐야 한다.
실전 팁
CLAUDE.md에 Git 규칙 추가
## Git 규칙 (CLAUDE.md에 포함)
브랜치 네이밍:
- 기능: feature/[영어-슬러그]
- 버그: fix/[이슈번호]-[영어-슬러그]
- 핫픽스: hotfix/[영어-슬러그]
커밋 메시지 (Conventional Commits):
- feat: 새 기능
- fix: 버그 수정
- refactor: 리팩토링
- test: 테스트
- docs: 문서
PR 제목 형식: type(scope): 설명
PR 본문: 변경 사항, 테스트 방법, 관련 이슈 포함
금지:
- main에 직접 커밋
- --no-verify로 훅 우회
- 비밀키/환경변수 커밋
유용한 gh 명령어 모음
# Claude가 자주 사용하는 명령어
gh pr list # PR 목록
gh pr view 123 # PR 상세
gh pr diff 123 # PR diff 확인
gh issue list # 이슈 목록
gh issue view 42 # 이슈 상세
gh run list # GitHub Actions 실행 목록
gh run view 12345 # Actions 실행 상세
gh run watch # 현재 실행 중인 Actions 실시간 모니터링
자주 묻는 질문
Claude Code에 GitHub 토큰을 어디에 저장하나요?
gh auth login으로 인증하면 시스템 키체인에 저장된다. Claude Code가 gh 명령을 실행할 때 자동으로 사용한다. 별도로 API 키를 Claude에게 전달할 필요 없다.
GitHub Actions에서 ANTHROPIC_API_KEY는 어떻게 설정하나요?
GitHub 레포 → Settings → Secrets and variables → Actions → New repository secret에서 ANTHROPIC_API_KEY 추가.
Claude가 실수로 main에 커밋할 수 있나요? CLAUDE.md에 "절대 main에 직접 커밋 금지" 명시하고, GitHub 레포에서 Branch protection rules로 main에 직접 푸시를 차단하면 이중으로 방지된다.
CI 코드 리뷰 비용은 얼마나 드나요? PR당 Sonnet 사용 시 diff 크기에 따라 $0.02-0.10. 하루 10개 PR이면 월 $6-30. 허용 가능한 비용이다.
한국어 커밋 메시지를 써도 되나요? 기술적으로 가능하지만, 영어 커밋 메시지를 권장한다. 국제 협업, 오픈소스 기여, 나중에 검색 효율성 때문이다. CLAUDE.md에 언어를 명시하면 Claude가 따른다.
관련 가이드
- Git Workflows in Claude Code — Git 워크플로우 심화
- Claude Code MCP 서버 TOP 10 — GitHub MCP 설정
- Claude Code 완벽 가이드 — 기본 가이드
더 깊이 알고 싶다면
Power Prompts 300 — $29 — GitHub 연동 워크플로우 프롬프트 25개 + PR 템플릿 + CI 코드 리뷰 커스터마이징 가이드.
30일 환불 보장. 즉시 다운로드.