Claude Code GitHub Actions 통합 완전 가이드 — @claude PR 자동화
anthropics/claude-code-action v1.0 GA 기반 @claude PR 자동화 워크플로우를 공식 문서 1차 자료로 정리한다. YAML 구조·v1 breaking changes·Skills 호출·비용 가드까지 운용 관점으로 다룬다.
들어가며
GitHub PR에서 @claude 이 코드 리뷰해줘를 남기면 몇 초 내로 Claude가 답변을 달아주는 것이 이제 공식으로 가능하다. Anthropic이 claude-code-action v1.0을 GA(General Availability)로 배포하면서 베타 기간의 불안정성이 해소됐다.
이 글은 그 워크플로우를 처음 설정하거나, 기존 v0 설정을 v1으로 마이그레이션하는 데 필요한 정보를 1차 자료 기반으로 정리한다.
다룰 내용:
anthropics/claude-code-action의 실행 흐름과 권한 모델@claude트리거를 받는 기본 워크플로우 YAML 구조- 시나리오별 고급 패턴 (PR 열릴 때 자동 리뷰, 이슈 트리아지 등)
- GitHub Actions 내에서
custom_instructions로 워크플로우 제어하는 방법 - 비용 폭주를 막는 가드 설정
- v0 → v1 breaking changes 마이그레이션 표
관련 배경 지식은 이 블로그의 다른 포스트에서 보강할 수 있다:
- Claude Code Hooks 완전 가이드 — 라이프사이클 이벤트 자동화
- CLAUDE.md · AGENTS.md 설계 패턴 — 에이전트 컨텍스트 설계
- Claude Code 서브에이전트 설계 패턴 — 에이전트 분리 기준
1. 아키텍처: GitHub Actions 내부 실행 흐름
anthropics/claude-code-action1은 GitHub Actions 워크플로우 위에서 Claude Code를 실행하는 공식 액션이다. 로컬 Claude Code 세션과 동일한 에이전트 환경이 Actions 러너에서 실행된다.
sequenceDiagram
participant D as 개발자
participant GH as GitHub
participant AC as Actions Runner
participant CC as Claude Code Agent
participant A as Anthropic API
D->>GH: PR 코멘트: "@claude 리뷰해줘"
GH->>AC: issue_comment 이벤트 트리거
AC->>AC: claude-code-action 시작
AC->>CC: GitHub 컨텍스트 주입<br/>(PR diff, 코멘트, 저장소 정보)
CC->>A: Anthropic API 호출
A-->>CC: Claude 응답
CC->>GH: PR 코멘트 작성 (gh CLI)
CC->>GH: 필요 시 파일 Push·커밋
GH-->>D: 알림
권한 모델
액션은 두 가지 토큰을 사용한다.
| 토큰 | 역할 | 기본값 |
|---|---|---|
anthropic_api_key | Anthropic API 인증 | 없음 (필수 입력) |
github_token | PR 코멘트·커밋·파일 변경 | $ |
GITHUB_TOKEN을 쓸 경우 워크플로우 YAML에서 필요한 권한을 명시해야 한다.
1
2
3
4
permissions:
contents: write # 파일 커밋·Push
pull-requests: write # PR 코멘트 작성
issues: write # 이슈 코멘트 작성
최소 권한 원칙: 실제로 사용하는 권한만 열어두는 것이 좋다. 코드 수정 없이 리뷰만 한다면
contents: read로 제한할 수 있다.
2. 기본 설정: @claude 트리거 워크플로우
전제 조건
- 저장소 Settings → Secrets and variables → Actions에
ANTHROPIC_API_KEY등록 - GitHub Actions가 활성화된 저장소
최소 동작 워크플로우
.github/workflows/claude.yml에 아래를 작성한다.2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
name: Claude PR Assistant
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
jobs:
claude:
if: |
contains(github.event.comment.body, '@claude') &&
github.event.comment.author_association != 'NONE'
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
issues: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
author_association != 'NONE'은 저장소와 아무 관계가 없는 익명 사용자의 트리거를 차단한다. API 비용 보호의 1차 방어선이다.
트리거 이벤트 종류
claude-code-action은 다음 GitHub 이벤트와 함께 동작한다.
| 이벤트 | 트리거 조건 | 주요 사용처 |
|---|---|---|
issue_comment | PR 또는 이슈에 코멘트 | @claude 인터랙티브 트리거 |
pull_request_review_comment | PR 코드 라인에 리뷰 코멘트 | 코드 라인 단위 질문 |
pull_request_review | 리뷰 제출 | 리뷰 본문 트리거 |
pull_request | PR 열기·업데이트 | 자동 리뷰 (비대화형) |
issues | 이슈 열기·편집 | 이슈 분석·레이블링 |
대화형 vs 자동 실행 (v1.0 자동 감지)
v1.0은 mode 설정 자체를 없애고 워크플로우 구성에 따라 자동으로 모드를 감지한다.2
| 방식 | 설명 | 입력 |
|---|---|---|
| 대화형 (interactive) | @claude 멘션에 반응, 코멘트 맥락 추적 | prompt 생략 |
| 자동 실행 (automation) | 트리거 즉시 지정 프롬프트 실행 | prompt: "..." |
자동 실행 예시 — PR이 열릴 때 자동으로 리뷰 코멘트를 단다:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
on:
pull_request:
types: [opened, synchronize]
jobs:
auto-review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
prompt: |
이 PR의 변경 사항을 검토하고 다음을 확인해 주세요:
1. 명백한 버그 또는 로직 오류
2. 보안 취약점 (SQL injection, XSS, 경로 순회 등)
3. 누락된 에러 핸들링
리뷰 결과를 PR 코멘트로 작성하세요.
3. 주요 입력 파라미터
claude-code-action v1의 입력 인터페이스는 통합된 prompt + CLI 패스스루 (claude_args) 두 축이다.2 모델·턴 수·도구 허용·시스템 프롬프트 추가 등은 모두 별도 파라미터가 아니라 claude_args로 CLI 옵션을 그대로 넘긴다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
anthropic_api_key | string | Claude API 인증 키 (직접 API 사용 시 필수) |
github_token | string | GitHub 작업용 토큰 (기본: $) |
prompt | string | 지시 (자동 모드) 또는 생략 (대화형 모드) |
claude_args | string | Claude Code CLI 인자 패스스루 — --max-turns, --model, --allowedTools, --disallowedTools, --append-system-prompt, --mcp-config 등 |
trigger_phrase | string | 기본 @claude 외 사용자 정의 멘션 |
plugin_marketplaces | string (multi-line) | 설치할 플러그인 마켓플레이스 Git URL |
plugins | string (multi-line) | 설치할 플러그인 이름 |
use_bedrock / use_vertex | bool | Amazon Bedrock / Google Vertex AI 사용 |
1
2
3
4
5
6
7
8
9
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
prompt: "PR 변경 사항을 리뷰하세요"
claude_args: |
--model claude-opus-4-7
--max-turns 5
--allowedTools "Bash,Read,Write,Edit"
--append-system-prompt "이 저장소는 Ruby on Rails 프로젝트입니다. bundle exec rspec으로 테스트를 실행하세요. CLAUDE.md의 규칙을 반드시 따르세요."
claude_args는 단순 문자열이므로 줄바꿈을 그대로 전달할 수 있는 multi-line YAML(|) 형식이 권장된다.
4. 시나리오별 고급 패턴
시나리오 1 — 특정 라벨이 붙은 PR에만 자동 리뷰
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
name: Claude Auto Review
on:
pull_request:
types: [labeled]
jobs:
review:
if: github.event.label.name == 'needs-review'
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
prompt: |
PR 변경 사항을 리뷰하고 개선 제안을 코멘트로 작성하세요.
시나리오 2 — 이슈 자동 트리아지
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
name: Issue Triage
on:
issues:
types: [opened]
jobs:
triage:
runs-on: ubuntu-latest
permissions:
issues: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
prompt: |
이 이슈를 분석하고 다음을 수행하세요:
1. 버그/기능요청/문서 중 어느 유형인지 판단
2. 재현 단계가 명확한지 확인
3. 이슈에 요약 코멘트 작성
시나리오 3 — PR 코드 라인 단위 질문에 답변
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name: Claude Review Assistant
on:
pull_request_review_comment:
types: [created]
jobs:
respond:
if: contains(github.event.comment.body, '@claude')
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
이 설정에서 리뷰어가 특정 코드 라인에 @claude 이 부분이 왜 필요해?라고 남기면, Claude가 해당 라인의 컨텍스트를 포함해 답변한다.
graph LR
A["PR 코드 라인\n리뷰 코멘트\n'@claude ...'"] --> B["pr_review_comment\n이벤트"]
B --> C["claude-code-action\n실행"]
C --> D["GitHub 컨텍스트\n주입: diff·코멘트 스레드"]
D --> E["Claude 응답\n→ 코멘트 게시"]
style C fill:#7c3aed,color:#fff
style E fill:#10b981,color:#fff
5. claude_args로 워크플로우 제어
v1.0에서 동작 제어는 모두 claude_args(Claude Code CLI 인자 패스스루)로 모인다. 시스템 프롬프트 추가는 --append-system-prompt, 도구 제한은 --allowedTools / --disallowedTools 옵션을 사용한다.
CLAUDE.md 연동
저장소에 CLAUDE.md가 있다면 Actions 환경에서도 자동으로 로드된다. 단, actions/checkout을 먼저 실행해 저장소를 체크아웃해야 CLAUDE.md가 로드된다.2 --append-system-prompt에는 Actions 환경 특화 지시만 추가하면 된다.
1
2
3
4
5
6
7
8
9
10
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
claude_args: |
--append-system-prompt "GitHub Actions 환경에서 실행 중입니다.
- 대화형 명령어 실행 금지 (sudo, vim 등)
- 변경 사항은 PR 코멘트로 제안하되 사용자가 명시적으로 요청하기 전에는 파일을 직접 수정하지 마세요
- 테스트: bundle exec rspec spec/ --format documentation"
도구 제한으로 안전 경계 설정
1
2
3
4
5
6
7
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
claude_args: |
--allowedTools "Read,Bash(git log:*),Bash(git diff:*)"
--disallowedTools "Bash(rm:*),Bash(curl:*),Write"
--append-system-prompt "코드를 읽고 분석하되 파일 수정은 하지 마세요. 필요한 변경 사항은 코멘트로 제안만 하세요."
--allowedTools와--disallowedTools는Bash(command-pattern:*)형식으로 특정 명령을 허용·차단할 수 있다.
언어·프레임워크별 --append-system-prompt 예시
1
2
3
4
5
6
7
8
9
10
11
12
13
# Rails 프로젝트
claude_args: |
--append-system-prompt "Ruby on Rails 7.1 프로젝트입니다.
- 테스트: bundle exec rspec
- 린트: bundle exec rubocop
- DB 마이그레이션은 직접 실행하지 말고 제안만 하세요"
# TypeScript 프로젝트
claude_args: |
--append-system-prompt "TypeScript + Next.js 프로젝트입니다.
- 빌드: npm run build
- 테스트: npm test
- any 타입 사용 금지, unknown + 타입 가드 사용"
6. 비용 가드와 운영 안전장치
GitHub Actions로 Claude를 실행하면 두 가지 비용이 발생한다.
- Anthropic API 비용: Claude 모델 호출 (입력·출력 토큰 기반)
- GitHub Actions 비용: 러너 실행 시간 (분 단위, 프라이빗 저장소만 청구)
가격은 Anthropic 공식 pricing 페이지를 참고하되, 모델 가격은 수시로 변동될 수 있다 (2026년 5월 기준). 실제 운용 전 최신 가격을 확인하라.
비용 폭주 방지 4단계 가드
1단계 — 트리거 조건 제한
1
2
3
4
5
6
jobs:
claude:
if: |
contains(github.event.comment.body, '@claude') &&
github.event.comment.author_association != 'NONE' &&
github.event.comment.author_association != 'FIRST_TIME_CONTRIBUTOR'
author_association 값:
| 값 | 대상 |
|---|---|
OWNER | 저장소 소유자 |
MEMBER | org 멤버 |
COLLABORATOR | 협업자로 등록된 외부인 |
CONTRIBUTOR | 이전에 커밋한 적 있는 외부인 |
FIRST_TIME_CONTRIBUTOR | 처음 기여하는 외부인 |
NONE | 저장소와 아무 관계 없는 사용자 |
신뢰할 수 있는 범위를 명확히 제한하면 외부인의 무분별한 API 호출을 차단할 수 있다.
2단계 — 타임아웃과 턴 제한
1
2
3
4
5
6
7
8
9
jobs:
claude:
runs-on: ubuntu-latest
timeout-minutes: 10 # workflow job 레벨 타임아웃
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: $
claude_args: --max-turns 5 # 대화 턴 상한
액션 자체의 timeout 파라미터는 없으며, GitHub Actions의 job 레벨
timeout-minutes를 사용한다. 턴 제한은claude_args: --max-turns N으로 전달한다.
3단계 — 태스크에 맞는 모델 선택
| 모델 | 적합한 태스크 |
|---|---|
claude-haiku-4-5-20251001 | 간단한 코멘트 답변, 분류 작업 |
claude-sonnet-4-6 | 일반 코드 리뷰, PR 분석 |
claude-opus-4-7 | 복잡한 아키텍처 리뷰, 심층 분석 |
비용을 낮추려면 기본 태스크에 Haiku를, 심층 리뷰가 필요한 경우에만 Opus를 사용하는 워크플로우 분리를 고려할 수 있다.
4단계 — 동시 실행 제한
1
2
3
4
5
jobs:
claude:
concurrency:
group: claude-$
cancel-in-progress: true
동일한 PR에서 여러 @claude 트리거가 연속으로 발생하면 이전 실행을 취소하고 최신 것만 유지한다.
비용 가드 흐름
graph TD
A["@claude 멘션 감지"] --> B{"author_association\n검사"}
B -->|"NONE / FIRST_TIME_CONTRIBUTOR"| C["❌ 트리거 무시"]
B -->|"그 외"| D{"concurrency\n중복 체크"}
D -->|"이미 실행 중"| E["이전 실행 취소"]
D -->|"새 실행"| F["Actions Runner 시작"]
E --> F
F --> G["job timeout-minutes 타이머 시작"]
G --> H{"claude_args --max-turns\n초과?"}
H -->|"초과"| I["❌ 강제 종료"]
H -->|"미초과"| J["Claude 실행"]
J --> K["PR 코멘트 게시"]
style C fill:#ef4444,color:#fff
style I fill:#ef4444,color:#fff
style K fill:#10b981,color:#fff
7. v0 → v1 마이그레이션
claude-code-action v1.0은 v0(베타) 대비 입력 파라미터와 동작 방식이 변경됐다.2
Breaking Changes 요약표 (공식)
v1.0의 주요 변경은 mode 자동 감지와 별도 파라미터들의 claude_args 통합이다.2
| 항목 | v0 (beta) | v1.0 (GA) |
|---|---|---|
| 액션 참조 | @beta | @v1 |
mode | "tag" 또는 "agent" | (제거 — 자동 감지) |
direct_prompt | 별도 입력 | prompt |
override_prompt | 별도 입력 | prompt (GitHub 변수 포함) |
custom_instructions | 별도 입력 | claude_args: --append-system-prompt |
max_turns | 별도 입력 | claude_args: --max-turns |
model | 별도 입력 | claude_args: --model |
allowed_tools | 별도 입력 | claude_args: --allowedTools |
disallowed_tools | 별도 입력 | claude_args: --disallowedTools |
claude_env | 별도 입력 | settings JSON 형식 |
마이그레이션 예시
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# v0 (beta) — 마이그레이션 전
- uses: anthropics/claude-code-action@beta
with:
mode: "tag"
direct_prompt: "PR을 리뷰하세요"
anthropic_api_key: $
custom_instructions: "Ruby 프로젝트입니다"
max_turns: "10"
model: "claude-sonnet-4-6"
# v1.0 (GA) — 마이그레이션 후
- uses: anthropics/claude-code-action@v1
with:
prompt: "PR을 리뷰하세요"
anthropic_api_key: $
claude_args: |
--append-system-prompt "Ruby 프로젝트입니다"
--max-turns 10
--model claude-sonnet-4-6
v0 워크플로우가 있다면
@beta를@v1로 바꾸는 것만으로는 부족하다. (a)mode입력을 제거하고, (b)direct_prompt를prompt로 교체하고, (c)max_turns·model·custom_instructions등을 모두claude_args안의 CLI 옵션으로 옮긴다.
자동 모드 감지
v1.0에서 mode 파라미터가 제거됐다. 워크플로우 트리거(issue_comment + @claude 멘션 vs pull_request + prompt 지정)에 따라 대화형/자동 실행이 자동 결정된다.2
마치며
claude-code-action v1.0은 베타 기간의 불안정성을 해소하고, 파라미터 명세를 언더스코어 형식으로 통일했다. 새로 시작한다면 v1 문서를 기준으로 설정하면 되고, 기존 v0 워크플로우는 파라미터 이름 변환표를 보고 일괄 치환하면 된다.
운용 관점에서 핵심 사항을 정리하면:
- 트리거 제한 우선:
author_association조건으로 신뢰된 사용자만 실행 - 타임아웃과 max_turns 설정: 비용 폭주 방지의 1차 하드 리밋
- 모델을 명시 지정: 기본값이 릴리즈마다 변할 수 있으므로 고정
- 저장소 체크아웃 명시: v1부터는
actions/checkout을 직접 추가해야 CLAUDE.md가 로드됨 - v0 → v1 전환 시 파라미터 이름 일괄 교체:
@v1로 바꾸는 것만으로는 불충분
참고 자료
A등급 — 공식 문서 및 1차 자료
- Anthropic, “Claude Code GitHub Actions” — 공식 GitHub Actions 통합 가이드, 입력 파라미터 명세
- anthropics/claude-code-action — 공식 GitHub Actions 저장소, README 및 릴리즈 노트
관련 포스트 (본 블로그)
- Claude Code Hooks 완전 가이드
- CLAUDE.md · AGENTS.md 설계 패턴
- Claude Code 서브에이전트 설계 패턴
- Claude Code MCP 서버 구축 완전 가이드
anthropics/claude-code-action, GitHub 저장소. https://github.com/anthropics/claude-code-action ↩︎
Anthropic, Claude Code GitHub Actions, 공식 문서. https://code.claude.com/docs/en/github-actions ↩︎ ↩︎2 ↩︎3 ↩︎4 ↩︎5 ↩︎6 ↩︎7