Claude Code GitHub Actions v1 가이드

중급 8 min

공식 claude-code-action v1의 설치(/install-github-app), 워크플로우 구성, 권한 스코핑, 비용 제어, PR 리뷰 자동화/이슈 기반 코딩/배치 작업 패턴을 다루는 완벽 가이드입니다.

GitHub ActionsCIPR 자동화claude-code-action

/install-github-app으로 빠른 설정

The fastest way to get started is using the official GitHub App installation flow. Navigate to /install-github-app in the Claude Code documentation and click 'Install'. This creates a GitHub App with the minimum required permissions and automatically generates the necessary secrets for your repository. After installation, you'll have two secrets available in your repository: ANTHROPIC_API_KEY for API access and CLAUDE_CODE_GITHUB_APP credentials for GitHub API access. The GitHub App approach is recommended over personal access tokens because it provides fine-grained permissions, audit logging, and organization-level control. For organizations, an admin can install the app at the org level and selectively enable it for specific repositories. This gives you centralized control over which repos can use Claude Code in CI while maintaining per-repo workflow configuration.

# Step 1: Install GitHub App
# Visit: https://github.com/apps/claude-code/installations/new
# Select your repository → Install

# Step 2: Add API key as repository secret
# Settings → Secrets → Actions → New repository secret
# Name: ANTHROPIC_API_KEY
# Value: sk-ant-...

# Step 3: Create workflow file
mkdir -p .github/workflows

PR 리뷰 자동화

The most popular use case is automated PR reviews. When a pull request is opened or updated, Claude Code analyzes the diff, checks for bugs, security issues, and style violations, then posts review comments directly on the PR. The key configuration is the prompt — this is where you define your review standards. Be specific about what to check: security vulnerabilities, performance regressions, missing tests, API contract changes, and coding style. Reference your project's CLAUDE.md for project-specific conventions. Control costs by limiting max_turns (how many tool-call rounds Claude can take) and using allowed_tools to restrict which tools Claude can access. For reviews, Read, Grep, and Glob are usually sufficient — no need for Write or Bash access.

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

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

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this PR for:
            1. Security vulnerabilities (injection, auth bypass)
            2. Performance regressions (N+1 queries, missing indexes)
            3. Missing error handling
            4. Test coverage gaps
            Post findings as inline PR comments.
          allowed_tools: "Read,Grep,Glob"
          max_turns: 10

이슈 기반 코드 생성

Claude Code can automatically implement features or fix bugs when issues are created or labeled. This is particularly powerful for well-specified issues: create an issue with clear acceptance criteria, add a 'claude-implement' label, and Claude generates a PR with the implementation. The workflow triggers on issue events, reads the issue body for requirements, creates a feature branch, implements the changes, runs tests, and opens a PR linking back to the original issue. This creates a complete audit trail from requirement to implementation. For safety, restrict this to specific labels (e.g., 'claude-implement' or 'good-first-issue'). You don't want Claude attempting every issue automatically. Also set a max_turns limit to prevent runaway sessions on ambiguous issues.

# .github/workflows/claude-implement.yml
name: Claude Auto-Implement
on:
  issues:
    types: [labeled]

jobs:
  implement:
    if: github.event.label.name == 'claude-implement'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Read issue #${{ github.event.issue.number }}.
            Implement the requested changes:
            1. Create a feature branch
            2. Write the implementation
            3. Add tests
            4. Run tests to verify
            5. Open a PR linking to this issue
          allowed_tools: "Read,Write,Edit,Bash,Grep,Glob"
          max_turns: 30
          timeout_minutes: 15

비용 제어와 모범 사례

GitHub Actions minutes and Anthropic API costs can add up quickly if not managed. Set max_turns to limit how many tool-call rounds Claude can make — 10 for reviews, 20-30 for implementations. Use timeout_minutes to set a hard ceiling on execution time. Use allowed_tools to restrict capabilities per workflow. Review workflows only need read access (Read, Grep, Glob). Implementation workflows need write access but should still exclude dangerous tools. Never give Bash access in PR review workflows. Monitor costs by checking token usage in the workflow logs. Claude Code Action logs input/output token counts for each run. Set up budget alerts in your Anthropic dashboard and consider using concurrency groups to prevent parallel runs on the same PR. For organizations, use the GitHub App's permission system to control which repositories can trigger Claude Code workflows. Combine with branch protection rules to ensure Claude's PRs still require human approval before merging.

# Cost control best practices

# 1. Limit turns and timeout
max_turns: 10          # Max tool-call rounds
timeout_minutes: 10    # Hard time limit

# 2. Restrict tools per workflow
# Review (read-only):
allowed_tools: "Read,Grep,Glob"
# Implementation (write access):
allowed_tools: "Read,Write,Edit,Bash,Grep,Glob"

# 3. Concurrency control — prevent parallel runs on same PR
concurrency:
  group: claude-${{ github.event.pull_request.number }}
  cancel-in-progress: true

# 4. Cost monitoring in workflow logs
# Look for: "Token usage: X input, Y output (~$Z.ZZ)"

# 5. Branch protection — require human approval
# Settings → Branches → main → Require PR reviews
# Claude's PRs still need human review before merge

실행 미리보기

Claude Code GitHub Actions v1 가이드