Claude Code + GitHub Actions: CI/CD 파이프라인 자동화 완전 가이드

CI/CD에서 Claude Code가 필요한 이유

현대 소프트웨어 개발에서 CI/CD 파이프라인은 필수입니다. 코드가 커밋되면 자동으로 빌드, 테스트, 배포가 이루어지는 것은 이제 표준이 되었습니다. 그러나 기존 CI/CD 파이프라인에는 여전히 수동 작업이 필요한 영역이 많습니다. 코드 리뷰, 테스트 코드 작성, 문서 업데이트, 보안 감사 등은 자동화하기 어려운 작업으로 남아 있었습니다.

Claude Code는 이런 빈틈을 메울 수 있는 AI 도구입니다. GitHub Actions와 결합하면 PR이 올라올 때 자동으로 코드를 리뷰하고, 부족한 테스트를 생성하며, 변경된 API에 맞춰 문서를 업데이트하고, 보안 취약점을 스캔하는 완전한 자동화 파이프라인을 구축할 수 있습니다. 사람이 관여하지 않아도 코드 품질의 기본 수준이 보장됩니다.

실제로 Claude Code + GitHub Actions를 도입한 팀들의 사례를 보면, PR 처리 속도가 평균 50% 향상되었고, 테스트 커버리지는 20~30% 증가했으며, 보안 취약점의 사전 탐지율이 80% 이상으로 올라갔습니다. 특히 개발자들이 반복적인 작업에서 해방되어 핵심 비즈니스 로직에 집중할 수 있게 된 것이 가장 큰 효과입니다.

GitHub Actions 기초 빠르게 훑기

Claude Code 연동을 시작하기 전에, GitHub Actions의 핵심 개념을 빠르게 정리하겠습니다. 이미 GitHub Actions에 익숙하다면 다음 섹션으로 건너뛰어도 됩니다.

핵심 구성 요소

기본 워크플로우 구조

# .github/workflows/example.yml
name: 워크플로우 이름

on:                          # 트리거 이벤트
  pull_request:
    types: [opened, synchronize]
  push:
    branches: [main]

permissions:                 # 권한 설정
  contents: read
  pull-requests: write

jobs:                        # 작업 정의
  job-name:
    runs-on: ubuntu-latest   # 실행 환경
    steps:
      - uses: actions/checkout@v4  # 코드 체크아웃
      - name: 단계 이름
        run: echo "Hello"          # 셸 명령어 실행

GitHub Actions 워크플로우 파일은 .github/workflows/ 디렉토리에 YAML 형식으로 저장합니다. 파이프라인 정의가 코드와 함께 Git으로 관리되므로, 변경 이력 추적과 팀 협업이 용이합니다.

Claude Code Action 설정하기

Anthropic에서 공식 제공하는 anthropic/claude-code-action을 사용하면 GitHub Actions에서 Claude Code를 쉽게 실행할 수 있습니다. 설정 과정을 단계별로 살펴보겠습니다.

1단계: API 키 설정

먼저 Anthropic API 키를 GitHub 저장소의 시크릿으로 등록합니다.

1. GitHub 저장소에서 Settings > Secrets and variables > Actions로 이동합니다.
2. New repository secret을 클릭합니다.
3. Name에 ANTHROPIC_API_KEY, Value에 Anthropic API 키를 입력합니다.
4. Add secret을 클릭하여 저장합니다.

2단계: 기본 워크플로우 파일 생성

# .github/workflows/claude-code.yml
name: Claude Code CI

on:
  pull_request:
    types: [opened, synchronize, reopened]
  issue_comment:
    types: [created]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  claude-review:
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' &&
       contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Code Review
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-sonnet-4-20250514
          timeout_minutes: 10

위 워크플로우는 두 가지 상황에서 실행됩니다. 첫째, PR이 생성되거나 업데이트될 때 자동으로 코드 리뷰를 수행합니다. 둘째, PR 코멘트에 @claude를 멘션하면 해당 요청에 응답합니다. 이를 통해 자동 리뷰와 대화형 리뷰를 모두 지원할 수 있습니다.

3단계: CLAUDE.md로 리뷰 지침 설정

프로젝트 루트에 CLAUDE.md 파일을 추가하여 Claude Code가 CI/CD 환경에서 따를 규칙을 정의합니다.

# CLAUDE.md - CI/CD 환경 설정

## 프로젝트 정보
- 언어: TypeScript
- 프레임워크: Next.js 15 + React 19
- 테스트: Vitest + Testing Library
- 패키지 매니저: pnpm

## 리뷰 규칙
- PR의 모든 변경 파일을 검토합니다
- 보안 취약점은 반드시 CRITICAL로 표시합니다
- 테스트가 없는 로직 변경은 WARNING으로 표시합니다
- 코딩 컨벤션 위반은 INFO로 표시합니다

## 금지 사항
- any 타입 사용 금지
- console.log 프로덕션 코드에 남기지 않기
- 하드코딩된 비밀키 또는 URL 금지
- 미사용 import 금지

자동 코드 리뷰 워크플로우

가장 많이 사용되는 시나리오인 자동 코드 리뷰 워크플로우를 상세하게 구성해보겠습니다. 이 워크플로우는 PR이 올라오면 변경된 코드를 분석하고, 리뷰 결과를 PR 코멘트로 자동 게시합니다.

# .github/workflows/ai-code-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'src/**'
      - 'lib/**'
      - 'app/**'

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed
        run: |
          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx' | head -50)
          echo "files<> $GITHUB_OUTPUT
          echo "$FILES" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
          echo "count=$(echo "$FILES" | wc -l)" >> $GITHUB_OUTPUT

      - name: Claude Code Review
        if: steps.changed.outputs.count > 0
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-sonnet-4-20250514
          prompt: |
            다음 파일들의 변경 사항을 코드 리뷰해주세요:

            ${{ steps.changed.outputs.files }}

            리뷰 기준:
            1. [CRITICAL] 보안 취약점 (SQL 인젝션, XSS, 인증 우회 등)
            2. [WARNING] 버그 위험 (null 참조, 경쟁 조건, 에러 처리 누락)
            3. [WARNING] 성능 문제 (N+1 쿼리, 메모리 누수, 불필요한 렌더링)
            4. [INFO] 코딩 컨벤션 위반
            5. [INFO] 개선 제안

            각 항목에 파일명:라인번호, 설명, 수정 코드를 포함하세요.
            문제가 없으면 "리뷰 완료: 이슈 없음"으로 응답하세요.

위 워크플로우의 핵심 포인트를 설명하겠습니다. concurrency 설정은 같은 PR에 대해 이전 리뷰가 실행 중이면 취소하고 최신 코드로 다시 리뷰합니다. paths 필터는 소스 코드가 변경된 경우에만 리뷰를 실행하여 불필요한 비용을 절약합니다. 변경된 파일 목록을 head -50으로 제한하여 API 토큰 한도 초과를 방지합니다.

자동 테스트 생성 워크플로우

코드가 변경되면 Claude Code가 자동으로 부족한 테스트를 생성하는 워크플로우입니다. 테스트가 없는 함수를 감지하고, 적절한 단위 테스트를 작성하여 PR로 제출합니다.

# .github/workflows/auto-test-gen.yml
name: Auto Test Generation

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'src/**/*.ts'
      - 'src/**/*.tsx'
      - '!src/**/*.test.ts'
      - '!src/**/*.spec.ts'

permissions:
  contents: write
  pull-requests: write

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.head_ref }}
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Find files without tests
        id: untested
        run: |
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- 'src/**/*.ts' 'src/**/*.tsx' | grep -v '.test\.\|.spec\.\|__test__')
          UNTESTED=""
          for file in $CHANGED; do
            test_file="${file%.ts}.test.ts"
            test_file2="${file%.tsx}.test.tsx"
            spec_file="${file%.ts}.spec.ts"
            if [ ! -f "$test_file" ] && [ ! -f "$test_file2" ] && [ ! -f "$spec_file" ]; then
              UNTESTED="$UNTESTED $file"
            fi
          done
          echo "files=$UNTESTED" >> $GITHUB_OUTPUT

      - name: Generate tests with Claude Code
        if: steps.untested.outputs.files != ''
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            다음 파일들에 대한 테스트 코드를 생성해주세요:
            ${{ steps.untested.outputs.files }}

            테스트 작성 규칙:
            - Vitest와 Testing Library를 사용합니다
            - 파일명.test.ts 형식으로 같은 디렉토리에 생성합니다
            - 각 public 함수/컴포넌트에 최소 3개의 테스트 케이스를 작성합니다
            - 정상 케이스, 엣지 케이스, 에러 케이스를 포함합니다
            - describe/it 블록으로 구조화합니다
            - 한국어 테스트 설명을 사용합니다
          allowed_tools: "Write,Read,Glob,Grep,Bash"

      - name: Run generated tests
        run: |
          pnpm vitest run --reporter=verbose 2>&1 | tail -50

      - name: Commit and push tests
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "[email protected]"
          git add '*.test.ts' '*.test.tsx'
          if git diff --staged --quiet; then
            echo "No new tests to commit"
          else
            git commit -m "test: Claude Code가 자동 생성한 테스트 추가"
            git push
          fi

이 워크플로우는 PR에 포함된 소스 파일 중 테스트가 없는 파일을 찾고, Claude Code에게 테스트 코드 생성을 요청한 뒤, 생성된 테스트를 실행하여 통과하는지 확인하고, 통과한 테스트만 커밋합니다. 이를 통해 테스트 커버리지가 자동으로 향상됩니다.

문서 자동 업데이트 워크플로우

API가 변경되면 문서도 함께 업데이트해야 합니다. 하지만 현실에서는 문서 업데이트가 늘 뒤처집니다. Claude Code를 활용하면 코드 변경에 맞춰 자동으로 문서를 업데이트할 수 있습니다.

# .github/workflows/auto-docs.yml
name: Auto Documentation Update

on:
  push:
    branches: [main]
    paths:
      - 'src/api/**'
      - 'src/lib/**'

permissions:
  contents: write
  pull-requests: write

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Detect API changes
        id: api-changes
        run: |
          CHANGED=$(git diff --name-only HEAD~1 -- 'src/api/**' 'src/lib/**')
          echo "files<> $GITHUB_OUTPUT
          echo "$CHANGED" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Update documentation
        if: steps.api-changes.outputs.files != ''
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            다음 API 파일들이 변경되었습니다:
            ${{ steps.api-changes.outputs.files }}

            변경 내용을 분석하고 docs/ 디렉토리의 관련 문서를
            업데이트해주세요.

            업데이트 규칙:
            - API 엔드포인트의 요청/응답 스키마를 정확히 반영
            - 새로운 파라미터나 변경된 타입을 문서에 추가
            - 예제 코드를 변경 사항에 맞게 수정
            - CHANGELOG.md에 변경 사항 요약 추가
          allowed_tools: "Write,Edit,Read,Glob,Grep"

      - name: Create PR for docs update
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "[email protected]"
          BRANCH="docs/auto-update-$(date +%Y%m%d-%H%M%S)"
          git checkout -b $BRANCH
          git add docs/ CHANGELOG.md
          if git diff --staged --quiet; then
            echo "No documentation changes needed"
          else
            git commit -m "docs: API 변경에 따른 문서 자동 업데이트"
            git push origin $BRANCH
            gh pr create \
              --title "docs: API 문서 자동 업데이트" \
              --body "Claude Code가 API 변경 사항을 감지하고 문서를 자동 업데이트했습니다." \
              --base main \
              --head $BRANCH
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

이 워크플로우는 main 브랜치에 API 관련 코드가 푸시되면, 변경된 파일을 분석하고, 관련 문서를 자동으로 업데이트하여 별도의 PR로 생성합니다. 문서 변경은 자동 머지하지 않고 PR로 제출하여 사람의 검토를 거치도록 설계했습니다.

보안 스캐닝 파이프라인

보안 스캐닝은 CI/CD에서 가장 중요한 자동화 영역 중 하나입니다. Claude Code를 활용한 보안 스캐닝은 기존 SAST(Static Application Security Testing) 도구보다 맥락을 이해하는 분석이 가능합니다.

# .github/workflows/security-scan.yml
name: Security Scan

on:
  pull_request:
    types: [opened, synchronize]
  schedule:
    - cron: '0 9 * * 1'  # 매주 월요일 오전 9시

permissions:
  contents: read
  pull-requests: write
  security-events: write

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Dependency audit
        id: audit
        run: |
          pnpm audit --json > audit-result.json 2>&1 || true
          echo "has_vulnerabilities=$(jq '.metadata.vulnerabilities.total > 0' audit-result.json)" >> $GITHUB_OUTPUT

      - name: Claude Security Analysis
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            이 저장소의 보안 감사를 수행해주세요.

            1. 의존성 취약점 분석:
               audit-result.json 파일을 확인하고 위험도를 평가하세요.

            2. 코드 보안 분석 (src/ 디렉토리):
               - SQL 인젝션
               - XSS (Cross-Site Scripting)
               - CSRF 보호
               - 인증/인가 취약점
               - 하드코딩된 비밀키
               - 안전하지 않은 역직렬화
               - SSRF (Server-Side Request Forgery)
               - 경로 순회 (Path Traversal)

            3. 설정 보안 분석:
               - CORS 설정
               - CSP (Content Security Policy) 헤더
               - HTTPS 강제 설정
               - 쿠키 보안 속성

            각 발견 사항을 CRITICAL/HIGH/MEDIUM/LOW로 분류하고
            구체적인 수정 방안을 제시하세요.
            OWASP 또는 CWE 참조 번호를 포함하세요.

보안 스캔 자동 차단 설정

CRITICAL 또는 HIGH 취약점이 발견되면 PR 머지를 자동으로 차단할 수 있습니다. GitHub의 Branch Protection Rule과 결합하면 보안 기준을 통과하지 못한 코드는 절대 메인 브랜치에 들어갈 수 없습니다.

# 보안 스캔 결과에 따른 자동 차단 (위 워크플로우에 추가)
      - name: Check security results
        if: github.event_name == 'pull_request'
        run: |
          # Claude Code의 리뷰 결과에서 CRITICAL 이슈 확인
          CRITICAL_COUNT=$(gh pr view ${{ github.event.pull_request.number }} \
            --json comments \
            --jq '[.comments[] | select(.body | contains("[CRITICAL]"))] | length')

          if [ "$CRITICAL_COUNT" -gt "0" ]; then
            echo "::error::CRITICAL 보안 취약점이 $CRITICAL_COUNT건 발견되었습니다."
            echo "보안 이슈를 수정한 후 다시 제출해주세요."
            exit 1
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

배포 자동화와 롤백

Claude Code는 배포 프로세스에서도 유용하게 활용할 수 있습니다. 배포 전 최종 검증, 배포 후 상태 확인, 문제 발생 시 자동 롤백 판단 등의 작업을 수행합니다.

# .github/workflows/deploy.yml
name: Deploy with AI Verification

on:
  push:
    branches: [main]
    paths-ignore:
      - 'docs/**'
      - '*.md'

permissions:
  contents: read
  deployments: write

jobs:
  pre-deploy-check:
    runs-on: ubuntu-latest
    outputs:
      should_deploy: ${{ steps.check.outputs.should_deploy }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 5

      - name: AI Pre-deploy Analysis
        id: check
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            최근 5개 커밋의 변경 사항을 분석하고 배포 적합성을 판단하세요.

            확인 사항:
            1. 마이그레이션 스크립트가 필요한 DB 스키마 변경이 있는가?
            2. 환경 변수 추가/변경이 필요한가?
            3. Breaking change가 있는가?
            4. 성능에 영향을 줄 수 있는 변경이 있는가?

            결과를 JSON으로 출력하세요:
            {"should_deploy": true/false, "warnings": [...], "required_actions": [...]}

  deploy:
    needs: pre-deploy-check
    if: needs.pre-deploy-check.outputs.should_deploy == 'true'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: pnpm build

      - name: Deploy to production
        run: |
          # 배포 명령어 (Vercel, AWS, GCP 등)
          pnpm deploy --prod

      - name: Post-deploy health check
        run: |
          sleep 30
          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://your-app.com/health)
          if [ "$HTTP_STATUS" != "200" ]; then
            echo "::error::Health check failed with status $HTTP_STATUS"
            exit 1
          fi

전체 워크플로우 통합 예시

지금까지 살펴본 개별 워크플로우를 하나의 완전한 CI/CD 파이프라인으로 통합한 예시입니다. PR 생성부터 배포까지 전체 과정이 자동화됩니다.

# .github/workflows/full-pipeline.yml
name: Full CI/CD Pipeline

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: write
  pull-requests: write
  security-events: write

jobs:
  # 1단계: 코드 품질 검사
  lint-and-type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check

  # 2단계: AI 코드 리뷰 (린트 통과 후)
  ai-review:
    needs: lint-and-type-check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Claude Code Review
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            이 PR의 변경 사항을 종합적으로 리뷰해주세요.
            보안, 성능, 코딩 컨벤션, 테스트 커버리지를 확인하세요.

  # 3단계: 보안 스캔 (리뷰와 병렬 실행)
  security-scan:
    needs: lint-and-type-check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Security Analysis
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "src/ 디렉토리의 보안 취약점을 분석하세요. OWASP Top 10 기준."

  # 4단계: 테스트 실행 + 자동 테스트 생성
  test:
    needs: lint-and-type-check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.head_ref }}
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: pnpm install --frozen-lockfile
      - run: pnpm test -- --coverage
      - name: Check coverage threshold
        run: |
          COVERAGE=$(pnpm vitest run --coverage --reporter=json 2>/dev/null | jq '.total.lines.pct')
          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
            echo "::warning::테스트 커버리지가 80% 미만입니다: ${COVERAGE}%"
          fi

  # 5단계: 최종 게이트 (모든 검사 통과 필수)
  gate:
    needs: [ai-review, security-scan, test]
    runs-on: ubuntu-latest
    steps:
      - name: All checks passed
        run: echo "모든 CI 검사를 통과했습니다."

비용 최적화 전략

Claude Code를 CI/CD에서 사용하면 API 호출 비용이 발생합니다. 불필요한 비용을 줄이면서 효과를 극대화하는 전략을 소개합니다.

# 비용 최적화가 적용된 워크플로우 예시
jobs:
  ai-review:
    # draft PR은 건너뛰기
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # 변경된 소스 파일만 필터링
      - name: Filter changed files
        id: filter
        run: |
          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
            -- '*.ts' '*.tsx' ':!*.test.ts' ':!*.spec.ts' ':!*.d.ts' \
            | head -30)
          LINES=$(echo "$FILES" | wc -l)
          echo "files=$FILES" >> $GITHUB_OUTPUT
          echo "count=$LINES" >> $GITHUB_OUTPUT

      # 변경 파일이 있을 때만 실행
      - name: Claude Review
        if: steps.filter.outputs.count > 0
        uses: anthropic/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # 파일 수에 따라 모델 선택
          model: ${{ steps.filter.outputs.count > 10 && 'claude-sonnet-4-20250514' || 'claude-haiku-4-20250414' }}

트러블슈팅 가이드

Claude Code + GitHub Actions를 운영하면서 자주 발생하는 문제와 해결 방법을 정리했습니다.

문제 1: API 키 인증 실패

# 증상: "Invalid API key" 또는 "Authentication failed" 에러

# 해결 방법:
# 1. GitHub Secrets에 API 키가 올바르게 등록되었는지 확인
# 2. 시크릿 이름이 워크플로우에서 참조하는 이름과 일치하는지 확인
# 3. API 키에 충분한 크레딧이 있는지 확인
# 4. Organization 시크릿인 경우 저장소에 접근 권한이 있는지 확인

# 디버깅 단계
- name: Check API key
  run: |
    if [ -z "${{ secrets.ANTHROPIC_API_KEY }}" ]; then
      echo "::error::ANTHROPIC_API_KEY가 설정되지 않았습니다"
      exit 1
    fi
    echo "API key is configured (length: ${#ANTHROPIC_API_KEY})"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

문제 2: 타임아웃 발생

# 증상: 워크플로우가 시간 초과로 실패

# 원인: 분석할 파일이 너무 많거나, 프롬프트가 너무 복잡함

# 해결 방법:
# 1. timeout_minutes를 늘리기 (기본 10분 → 20분)
# 2. 분석 파일 수를 제한하기 (head -20 등)
# 3. 프롬프트를 간결하게 수정하기
# 4. 큰 PR은 여러 Job으로 분할하기

- name: Claude Review with timeout
  uses: anthropic/claude-code-action@v1
  timeout-minutes: 20
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    timeout_minutes: 15

문제 3: 권한 오류

# 증상: "Resource not accessible by integration" 에러

# 해결 방법: permissions 블록을 명시적으로 설정
permissions:
  contents: read         # 코드 읽기
  pull-requests: write   # PR에 코멘트 작성
  issues: write          # 이슈에 코멘트 작성
  security-events: write # 보안 이벤트 기록

# Fork된 PR의 경우 시크릿 접근이 제한됨
# pull_request_target 이벤트를 사용하되 보안에 주의
on:
  pull_request_target:
    types: [opened, synchronize]

문제 4: 리뷰 코멘트가 PR에 표시되지 않음

# 증상: 워크플로우는 성공했지만 PR에 코멘트가 없음

# 확인 사항:
# 1. pull-requests: write 권한이 있는지 확인
# 2. GITHUB_TOKEN에 충분한 권한이 있는지 확인
# 3. 워크플로우 로그에서 Claude Code의 출력 확인

# 수동으로 코멘트를 게시하는 대안
- name: Post comment manually
  if: always()
  uses: actions/github-script@v7
  with:
    script: |
      const fs = require('fs');
      const review = fs.readFileSync('review-output.txt', 'utf8');
      await github.rest.issues.createComment({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number,
        body: review
      });

실전 운영 팁

Claude Code + GitHub Actions 파이프라인을 안정적으로 운영하기 위한 실전 팁을 모았습니다.

1. 점진적 도입

처음부터 모든 자동화를 켜지 마세요. 먼저 코드 리뷰만 시작하고, 팀이 익숙해지면 테스트 생성, 문서 업데이트, 보안 스캐닝 순서로 확장하세요. 각 단계마다 최소 2주의 안정화 기간을 두는 것이 좋습니다.

2. 피드백 루프 구축

AI 리뷰의 품질을 지속적으로 개선하려면 피드백 루프가 필요합니다. 팀원들이 AI 리뷰 결과에 리액션(좋아요/싫어요)을 남기도록 하고, 정기적으로 오탐과 누락 사례를 분석하여 CLAUDE.md와 프롬프트를 개선하세요.

3. 모니터링 대시보드

워크플로우의 성공률, 평균 실행 시간, API 비용을 추적하는 대시보드를 만드세요. GitHub Actions의 API를 활용하거나, 자동화 가이드의 모니터링 섹션을 참고하세요.

4. 에스컬레이션 정책

AI가 CRITICAL 이슈를 발견했을 때의 에스컬레이션 정책을 미리 정해두세요. Slack 알림, 이메일 통보, PR 자동 차단 등의 액션을 설정할 수 있습니다. 훅 가이드를 참고하여 자동 알림 시스템을 구축할 수 있습니다.

Claude Code + GitHub Actions의 조합은 CI/CD 파이프라인의 새로운 표준을 제시합니다. 반복적이고 기계적인 작업을 AI에게 맡기고, 개발자는 더 창의적이고 가치 있는 일에 집중하세요. 오늘 첫 워크플로우를 만들어보는 것으로 시작하세요.

관련 리소스