공식 참고 자료: GitHub Actions · Overview · SDK
커리큘럼 흐름
- CLAUDE.md Mastery — 저장소 메모리와 규칙
- Effective Prompting — 작업 framing과 제약 설정
- MCP Power Tools — 도구와 라이브 컨텍스트 연결
- Multi-Agent Workflows — 위임과 병렬 실행
- Hooks Automation — 로컬 워크플로우 enforcement
- GitHub Actions Workflows — 반복 팀 자동화 ← 현재 문서
- Claude 첫날 안전 루프 — 입문 안전 루프
- Claude 중형 리팩토링 플레이북 — 중급 레인 운영
- Claude 고위험 변경 거버넌스 — 고급 릴리스 통제
- Claude 운영 매뉴얼 — 팀 단위 운영 리듬
이 문서에서 참고한 공식 문서
- GitHub Actions 안에서 Claude Code 사용하기 — GitHub Actions
- 자동화와 SDK 표면 — SDK
- Claude Code가 더 넓은 워크플로우에 들어가는 방식 — Overview
팀 자동화에서 Claude Code가 잘 맞는 지점
Claude Code는 원래 대화형 개발에 강하지만, Anthropic은 GitHub Actions 같은 자동화 흐름도 지원합니다.
좋은 사용 사례:
- 체크리스트 기반 PR 리뷰
- 이슈 triage
- 실패한 워크플로우 로그 요약
- 릴리즈 노트 초안 작성
- 라벨/코멘트 기반 반복 작업
자동화에 잘 맞는 일
다음 조건이면 잘 맞습니다.
- 작업 범위가 좁음
- 결과를 리뷰할 수 있음
- PR/issue 같은 실제 아티팩트에 연결됨
- 최종 판단은 여전히 사람이 함
자동화에 안 맞는 일
너무 넓은 제품 판단, 민감한 권한, 고위험 배포 변경은 여전히 사람 중심으로 다루는 편이 낫습니다.
실전 패턴
- PR, issue, label로 트리거
- 저장소 컨텍스트 제공
- Claude가 좁은 작업 수행
- 결과를 코멘트/요약/artifact로 남김
- merge 경로는 사람 유지
기본 설정
API 키 등록
GitHub 저장소에서 Settings → Secrets and variables → Actions로 이동해 ANTHROPIC_API_KEY를 추가합니다. 이 키가 없으면 워크플로우가 실행되지 않아요.
공식 액션 사용
Anthropic이 제공하는 공식 액션은 anthropics/claude-code-action@v1입니다. 별도로 Claude Code를 설치하거나 설정할 필요 없이 이 액션 하나면 됩니다.
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "여기에 Claude에게 할 작업을 씁니다."저장소 루트에 CLAUDE.md 파일이 있으면 액션이 자동으로 읽어서 코딩 규칙과 아키텍처 맥락을 파악합니다. 자동화 품질을 높이는 가장 간단한 방법 중 하나예요.
PR 리뷰 자동화 워크플로우
PR이 열리거나 새 커밋이 올라올 때마다 Claude가 자동으로 리뷰 코멘트를 달아줍니다.
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
이 PR을 다음 항목으로 리뷰해 주세요:
- 보안 취약점
- 성능 문제
- 코드 스타일 일관성
실행 가능한 피드백을 PR 코멘트로 달아주세요.permissions에서 pull-requests: write가 반드시 필요합니다. 없으면 코멘트를 달 수 없어요.
프롬프트는 구체적일수록 좋습니다. "코드를 리뷰해" 보다 "마이그레이션 위험과 누락된 에러 핸들링을 중심으로 리뷰해"가 훨씬 유용한 결과를 냅니다.
이슈 트리아지 워크플로우
새 이슈가 등록되면 Claude가 내용을 읽고 자동으로 라벨을 붙이고 첫 응답 코멘트를 작성합니다.
name: Issue Triage
on:
issues:
types: [opened]
jobs:
triage:
runs-on: ubuntu-latest
permissions:
contents: read
issues: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
방금 등록된 이슈를 분석해 주세요:
제목: ${{ github.event.issue.title }}
내용: ${{ github.event.issue.body }}
다음을 수행해 주세요:
1. 버그 리포트, 기능 요청, 질문 중 어느 것인지 판단
2. 재현 단계나 컨텍스트가 부족하면 추가 정보 요청 코멘트 작성
3. 적절한 라벨 제안 (bug, enhancement, question, needs-info)
4. 긴급도 평가 (critical, high, medium, low)
이슈 코멘트로 트리아지 요약을 작성해 주세요.이슈 트리아지는 특히 오픈소스 프로젝트에서 효과적입니다. 반복적인 초기 응답 작업을 크게 줄여줍니다.
실패 로그 분석 워크플로우
CI 워크플로우가 실패하면 Claude가 로그를 읽고 원인을 분석해서 PR에 요약 코멘트를 달아줍니다.
name: Analyze Failure
on:
workflow_run:
workflows: ["CI"]
types: [completed]
jobs:
analyze:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
actions: read
steps:
- name: Get workflow logs
id: logs
uses: actions/github-script@v7
with:
script: |
const logs = await github.rest.actions.downloadWorkflowRunLogs({
owner: context.repo.owner,
repo: context.repo.repo,
run_id: context.payload.workflow_run.id,
});
return Buffer.from(logs.data).toString('utf-8').slice(0, 8000);
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
아래는 실패한 CI 워크플로우의 로그입니다:
${{ steps.logs.outputs.result }}
다음을 분석해 주세요:
1. 가장 먼저 실패한 항목
2. 가능성 높은 근본 원인
3. 수정을 위한 구체적인 다음 단계
관련 PR에 분석 결과를 코멘트로 달아주세요.로그 전체를 넘기면 토큰이 많이 소모됩니다. 위 예시처럼 slice(0, 8000) 등으로 관련 부분만 잘라서 넘기는 게 비용 면에서 유리해요.
보안과 권한 설정
최소 권한 원칙
워크플로우에는 꼭 필요한 권한만 부여하세요. 코멘트만 달면 된다면 pull-requests: write만 있으면 됩니다. contents: write는 파일을 직접 수정할 때만 필요해요.
permissions:
contents: read # 코드 읽기
pull-requests: write # PR 코멘트 작성
issues: write # 이슈 코멘트 및 라벨
# actions: read # 워크플로우 로그 읽기 (필요할 때만)시크릿 관리
ANTHROPIC_API_KEY는 반드시 GitHub Secrets에 저장하세요. 코드에 직접 넣으면 절대 안 됩니다.- 환경별로 키를 분리하고 싶다면 GitHub Environments를 활용하세요.
- 키를 정기적으로 교체하는 습관을 들이면 좋습니다.
요청 빈도와 비용 고려
GitHub Actions 워크플로우를 실행할 때마다 Anthropic API 크레딧이 소모됩니다. 몇 가지 주의 사항이 있어요.
- 대형 저장소에서는 PR이 매우 자주 열릴 수 있습니다. 모든 PR에 리뷰 워크플로우를 붙이면 비용이 빠르게 쌓일 수 있어요.
paths필터로 특정 파일이 변경될 때만 실행되도록 제한할 수 있습니다.concurrency설정으로 같은 PR에서 중복 실행을 막을 수 있어요.
on:
pull_request:
paths:
- "src/**"
- "tests/**"
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true모범 사례
1. 읽기 전용 작업부터 시작하세요
자동 merge나 파일 수정보다 코멘트, 요약, 초안 생성부터 시작하세요. 결과를 눈으로 확인하면서 신뢰를 쌓은 다음 점진적으로 범위를 넓히는 게 안전합니다.
2. 사람이 merge를 결정하도록 유지하세요
Claude의 코멘트가 아무리 좋아도 최종 merge 결정은 사람이 해야 합니다. 자동 merge는 처음엔 편해 보이지만 뭔가 잘못됐을 때 원인을 찾기 어렵게 만들어요.
3. 타임아웃을 설정하세요
워크플로우가 무한정 실행되는 걸 방지하기 위해 timeout-minutes를 설정하세요.
jobs:
review:
runs-on: ubuntu-latest
timeout-minutes: 104. CLAUDE.md로 저장소 컨텍스트를 제공하세요
저장소 루트의 CLAUDE.md에 코딩 규칙, 아키텍처 결정, 리뷰 체크리스트를 작성해 두면 자동화의 품질이 크게 올라갑니다. Claude가 저장소의 맥락을 이해하고 리뷰할 수 있거든요.
예시 CLAUDE.md 내용:
## 코딩 규칙
- TypeScript strict 모드 사용
- 모든 API 엔드포인트에 에러 핸들링 필수
- 새 기능에는 반드시 테스트 추가
## 리뷰 체크리스트
- SQL 인젝션 가능성 확인
- 인증/인가 처리 확인
- 외부 입력 검증 확인5. 프롬프트를 구체적으로 작성하세요
모호한 프롬프트는 모호한 결과를 냅니다. 무엇을 확인해야 하는지, 어떤 형식으로 결과를 달아야 하는지 명확하게 써주세요.
SDK 기반 고급 자동화
공식 액션 외에도 Claude Code CLI를 직접 CI에서 사용할 수 있어요. 더 세밀한 제어가 필요할 때 유용합니다.
name: Claude Code CI Tasks
on:
push:
branches: [main]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Security Audit
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude -p "Audit the files changed in this push for security vulnerabilities. \
Focus on: SQL injection, XSS, auth bypasses. \
Output a markdown summary." \
--output-format text > security-report.md
- name: Upload Report
uses: actions/upload-artifact@v4
with:
name: security-report
path: security-report.md- CLI를 직접 사용하면 공식 액션보다 더 세밀한 제어가 가능합니다. 커스텀 출력 형식, 파이프, 체이닝을 자유롭게 쓸 수 있어요.
--model haiku를 사용하면 대량 분석 시 비용을 크게 줄일 수 있습니다.--allowedTools "Read,Glob,Grep"을 사용하면 읽기 전용 작업으로 제한할 수 있어요.
릴리즈 노트 자동 생성
릴리즈가 생성되면 Claude가 커밋 히스토리를 분석해서 릴리즈 노트를 자동으로 작성합니다.
name: Release Notes
on:
release:
types: [created]
jobs:
generate-notes:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for commit analysis
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Generate release notes for tag ${{ github.event.release.tag_name }}.
Analyze all commits since the previous tag:
1. Group changes by category (Features, Bug Fixes, Performance, Documentation)
2. Write user-facing descriptions (not commit hashes)
3. Highlight breaking changes with ⚠️ prefix
4. Include migration steps if needed
Format as GitHub-flavored markdown.
Update the release body with the generated notes.fetch-depth: 0은 필수입니다. Claude가 태그 간 커밋을 비교하려면 전체 git 히스토리가 필요해요.- Conventional Commits(
feat:,fix:,breaking:)를 사용하는 저장소에서 가장 잘 동작합니다. CLAUDE.md에 변경 로그 형식 규칙을 작성해 두면 더 일관된 결과를 얻을 수 있어요.
매트릭스 전략으로 병렬 리뷰
여러 관점의 전문 리뷰를 동시에 실행할 수 있어요. GitHub Actions의 매트릭스 전략을 활용합니다.
name: Multi-Aspect Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
strategy:
matrix:
aspect:
- name: security
prompt: "Review for OWASP Top 10 vulnerabilities, injection risks, and auth issues"
- name: performance
prompt: "Review for N+1 queries, memory leaks, unnecessary re-renders, and heavy computations"
- name: maintainability
prompt: "Review for code duplication, complex functions (>20 lines), missing error handling, and unclear naming"
permissions:
contents: read
pull-requests: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
You are a ${{ matrix.aspect.name }} specialist.
${{ matrix.aspect.prompt }}
Be specific: reference file names and line numbers.
If no issues found, say "✅ No ${{ matrix.aspect.name }} issues found."- 각 관점(aspect)이 별도 잡으로 실행되기 때문에 진짜 병렬 처리입니다. 순차 실행이 아니에요.
- 각 리뷰가 한 가지 차원에만 집중하기 때문에, 넓고 얕은 리뷰보다 훨씬 깊이 있는 피드백을 받을 수 있습니다.
- 비용은 단일 리뷰의 약 3배이지만, 그만큼 훨씬 꼼꼼합니다.
if: contains(github.event.pull_request.labels.*.name, 'deep-review')를 추가하면 특정 라벨이 붙은 PR에서만 실행되도록 제한할 수 있어요.
의존성 업데이트 자동화
매주 정해진 시간에 의존성을 점검하고, 보안 패치가 필요하면 자동으로 PR을 생성합니다.
name: Weekly Dependency Check
on:
schedule:
- cron: "0 9 * * 1" # Every Monday at 9 AM
workflow_dispatch: # Manual trigger
jobs:
check-deps:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Check for outdated dependencies in this project:
1. Run `npm outdated` (or equivalent for the package manager used)
2. For each outdated package, check:
- Is it a major version bump? (potential breaking changes)
- Does the changelog mention security fixes?
- Are there known vulnerabilities? (check `npm audit`)
3. Create a summary categorized by:
- 🔴 Security patches (update immediately)
- 🟡 Minor updates (safe to update)
- 🟠 Major updates (needs review)
4. If there are security patches, create a PR with those updates
Be conservative — only auto-update for security patches.
Major version bumps should only be recommended, not applied.schedule로 cron을 설정하면 정기적인 유지보수가 자동화됩니다.workflow_dispatch를 같이 설정하면 필요할 때 수동으로도 실행할 수 있어요.- 보수적인 접근 방식입니다. 보안 패치만 자동 PR을 만들고, 나머지는 권장 사항으로 보고해요.
CLAUDE.md에 의존성 관리 정책을 작성해 두면 Claude가 더 일관된 판단을 할 수 있습니다.
Claude와 Codex의 차이
- Claude: 리뷰, 설명, 요약에 강함
- Codex: 경계 있는 실행, 코드 수정, 검증에 강함
처음엔 merge보다 comment부터
가장 안전한 시작점은 자동 merge가 아니라 자동 코멘트, 요약, 초안 생성입니다.