Claude Code GitHub Actions 완전 이해 가이드
핵심 요약
Claude Code GitHub Actions는 GitHub 이슈·PR에 @claude를 호출해 코드 리뷰, 구현, 수정 등을 자동화하는 액션이다.
v1에서는 설정이 단순해지고 prompt와 claude_args 중심의 통일된 인터페이스와 자동 모드 감지가 도입되었다.
Claude API 직접 사용뿐 아니라 AWS Bedrock, Google Vertex AI와도 연동해 엔터프라이즈 환경에서 안전하게 사용할 수 있다.
Claude Code GitHub Actions 개념 잡기
Claude Code GitHub Actions는 GitHub Actions 위에서 돌아가는 "AI 개발 보조 봇"이다.
사용자는 이슈나 PR 댓글에 @claude라고 태그하거나, 워크플로우에서 미리 정의한 prompt를 실행해 코드 리뷰, PR 생성, 버그 수정 등 다양한 작업을 자동으로 수행시킬 수 있다.
이 기능은 내부적으로 Claude Code SDK를 사용하며, GitHub 액션 외에도 별도 애플리케이션에서 같은 SDK를 활용해 더 복잡한 자동화 파이프라인을 만들 수도 있다.
기본 모델은 Claude Sonnet 계열이며, 필요한 경우 모델 파라미터를 설정해 Opus 4.5 (claude-opus-4-5-20251101)와 같은 더 강력한 모델을 활용할 수 있다.
Claude Code로 할 수 있는 일
Claude Code GitHub Actions가 제공하는 핵심 가치는 "텍스트 명령 → 실제 코드 변경"까지 이어지는 자동화이다.
이슈나 PR 댓글에서 다음과 같이 사용할 수 있다.
@claude implement this feature based on the issue description@claude fix the TypeError in the user dashboard component
이렇게 지시하면 Claude는 관련 파일을 찾아 분석하고, 수정된 코드를 포함한 커밋이나 PR을 생성할 수 있다.
또한 예약 실행(schedule)을 이용해 "어제 커밋과 이슈 요약" 같은 리포트를 매일 자동으로 생성하는 등 일반적인 코드 작업 외의 자동 레포트에도 활용 가능하다.
v1에서 단순해진 설정 구조
v1.0은 베타 대비 설정이 크게 단순화되었고, 몇 가지 "깨지는 변경(breaking changes)"가 있다.
가장 큰 변화는 모드 설정 제거이다. 예전에는 mode: "tag" / mode: "agent"를 통해 태그 기반·자동 실행 모드를 구분했지만, 이제는 설정을 보고 액션이 스스로 모드를 판단한다. prompt가 없고 이슈/PR 코멘트 이벤트라면 @claude 멘션에 반응하는 인터랙티브 모드로, prompt가 지정되어 있으면 바로 자동 실행 모드로 동작한다.
또한 입력 파라미터 이름이 통합되었다. direct_prompt는 prompt로 바뀌었고, model, max_turns, custom_instructions 등은 모두 CLI 인자 형식의 claude_args로 넘겨야 한다. 예를 들어:
- uses: anthropics/claude-code-action@v1
with:
prompt: "Review this PR for security issues"
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: |
--system-prompt "Follow our coding standards"
--max-turns 10
--model claude-sonnet-4-5-20250929이 구조를 이해해 두면 베타에서 v1으로 마이그레이션할 때도, 새 워크플로우를 설계할 때도 훨씬 수월하다.
기본 설치와 빠른 시작
가장 쉬운 방법은 Claude 터미널 앱에서 /install-github-app 명령을 실행하는 것이다.
이 명령은 Claude GitHub 앱 설치와 ANTHROPIC_API_KEY 시크릿 등록, 예제 워크플로우 추가를 순서대로 안내해 준다. 이때 리포지토리 관리자 권한이 필요하며, 앱은 "Contents / Issues / Pull requests"에 읽기·쓰기 권한을 요청한다.
이 자동 설치가 안 되거나 직접 통제하고 싶다면 수동 설정을 사용하면 된다.
GitHub 앱
Claude를 설치하고 필요한 리포지토리에 권한 부여리포지토리 Settings → Secrets에
ANTHROPIC_API_KEY등록공식 레포지토리의
examples/claude.yml를.github/workflows/에 복사 후 필요에 맞게 수정
이후 이슈나 PR에서 @claude를 태그해 동작을 테스트하면 된다.
워크플로우 설계 패턴: 이벤트, prompt, claude_args
Claude Code GitHub Actions는 GitHub 이벤트를 트리거로 실행된다. 대표적인 패턴은 세 가지다.
첫째, "멘션 반응형" 패턴이다.
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
jobs:
claude:
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# prompt 없이 두면 @claude 멘션에 자동 응답여기서는 prompt를 생략해두면 코멘트 텍스트에 있는 @claude를 감지해 대화형으로 응답한다.
둘째, "slash 명령 기반 자동화" 패턴이다.
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "/review"
claude_args: "--max-turns 5"여기서 /review는 Claude Code에서 제공하는 미리 정의된 프롬프트로, 리뷰 관점의 행동을 수행한다.
셋째, "완전히 자동화된 batch 작업" 패턴이다.
on:
schedule:
- cron: "0 9 * * *"
jobs:
report:
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "Generate a summary of yesterday's commits and open issues"
claude_args: "--model claude-opus-4-5-20251101"이 경우 사람의 코멘트를 기다리지 않고 크론에 맞춰 자동 실행된다.
prompt vs claude_args: 역할과 활용법
prompt와 claude_args를 이해하면, 거의 모든 행동을 설계할 수 있다.
prompt는 Claude에게 무엇을 시킬지에 대한 "주요 지시문"이다. 자연어 텍스트로 직접 작성하거나, /review, /fix 같은 슬래시 커맨드로 간단히 호출할 수 있다. 이 프롬프트에 GitHub 컨텍스트 변수(예: PR 제목, 브랜치 이름)를 조합해 "이 PR의 변경 사항에 대해 성능 관점으로만 리뷰해 줘"와 같은 특화된 지시도 만들 수 있다.
claude_args는 Claude Code CLI에 직접 전달되는 "세부 옵션"이다. 모델·대화 길이·도구 제한 등 동작 방식의 매개변수를 조정한다.
예시:
claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929 --allowed-tools git,editor --debug"이렇게 설정하면 대화는 최대 5턴만 진행되고, 특정 도구만 사용할 수 있으며, 디버그 로그도 출력할 수 있다.
결국 prompt는 "무엇을 할지", claude_args는 "어떻게 할지"를 정의하는 축이라고 이해하면 된다.
CLAUDE.md로 코드 스타일과 규칙 주입하기
프로젝트별 코드 스타일과 규칙을 반복해서 설명하는 대신, 리포지토리 루트에 CLAUDE.md 파일을 두어 기준을 고정할 수 있다.
여기에는 예를 들어 "React에서는 함수형 컴포넌트만 사용", "에러는 항상 커스텀 Error 클래스로 래핑", "테스트는 Jest를 사용하며, given-when-then 패턴으로 작성"과 같은 세부 규칙을 적어둘 수 있다.
Claude는 이 문서를 읽고 PR 생성·코드 수정·리뷰에 반영한다. 즉, 여러 개발자가 섞여 있는 프로젝트에서도 AI가 팀의 "집단 습관"을 따라가도록 만드는 장치이다.
주의할 점은 너무 길고 산만하게 쓰지 않는 것이다. 핵심 규칙·예시 위주로 짧고 명확하게 정리할수록 Claude가 일관되게 해석하기 쉽다.
보안과 비용: 꼭 알아야 할 운영 상식
Claude Code GitHub Actions는 GitHub 호스티드 러너에서 실행되며, 코드와 시크릿은 GitHub의 보안 모델을 따른다.
가장 중요한 보안 원칙은 "API 키를 절대 코드에 하드코딩하지 않는다"이다. 항상 리포지토리 시크릿에 ANTHROPIC_API_KEY 등으로 등록한 뒤, 워크플로우에서 ${{ secrets.XXX }} 형식으로 참조해야 한다.
또한 GitHub 앱 권한은 필요한 범위에만 부여하고, Bedrock/Vertex 연동 시 OIDC·Workload Identity Federation 등 "키 없는" 인증 방식을 사용해 정적 키 유출 위험을 줄이는 것이 좋다.
비용 측면에서 두 가지 축을 관리해야 한다.
하나는 GitHub Actions 실행 시간이다. Claude 작업도 결국 GitHub 러너 시간을 소모하므로, 오너·오거나이제이션의 Actions 요금 정책에 반영된다.
다른 하나는 Claude API(혹은 Bedrock/Vertex에서의 모델 호출) 비용이다. 프롬프트와 응답 길이에 따라 토큰 사용량이 달라지고, 복잡한 작업일수록 비용이 늘어난다.
이를 줄이려면 다음과 같은 전략이 유효하다.
--max-turns로 대화 길이 제한특정 이벤트(예: PR 오픈 시에만)로 트리거 제한
@claude호출을 세밀한 명령 위주로 사용해 불필요한 대화 회수를 줄이기워크플로우 타임아웃과 GitHub concurrency 설정으로 동시에 도는 작업 수 제한
AWS Bedrock / Google Vertex AI와의 연동 구조
엔터프라이즈 환경에서 자사 클라우드 인프라를 활용하려면, Claude API 직접 호출 대신 AWS Bedrock 또는 Google Vertex AI를 사용할 수 있다.
공통 패턴은 다음과 같다.
GitHub Actions → 클라우드(IAM/OIDC/Workload Identity)를 통해 임시 자격 증명 획득
Claude Code 액션은
use_bedrock: "true"또는use_vertex: "true"플래그로 클라우드 백엔드를 사용claude_args에서 해당 플랫폼에 맞는 모델 ID를 지정
예를 들어 AWS Bedrock 워크플로우에서는 aws-actions/configure-aws-credentials@v4로 OIDC 기반 IAM 역할을 가져오고, Claude 액션에 다음과 같이 설정한다.
- uses: anthropics/claude-code-action@v1
with:
github_token: ${{ steps.app-token.outputs.token }}
use_bedrock: "true"
claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0 --max-turns 10'Bedrock의 모델 ID는 지역 프리픽스와 버전이 포함된다는 점이 특징이다.
Vertex AI 통합에서는 google-github-actions/auth@v2로 Workload Identity Federation을 통해 서비스 계정을 가장하고, 환경변수로 프로젝트 ID와 지역을 넘긴다.
- uses: anthropics/claude-code-action@v1
with:
github_token: ${{ steps.app-token.outputs.token }}
trigger_phrase: "@claude"
use_vertex: "true"
claude_args: '--model claude-sonnet-4@20250514 --max-turns 10'
env:
ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
CLOUD_ML_REGION: us-east5이 구조를 쓰면 API 키를 따로 저장할 필요 없이, GitHub와 클라우드 간의 신뢰 관계만으로 안전하게 모델을 호출할 수 있다.
트러블슈팅과 자주 생기는 문제들
@claude에 반응하지 않거나 인증 오류가 날 때는 대부분 설정 문제다.
먼저 멘션 반응 문제라면 다음을 체크해야 한다.
Claude GitHub 앱이 해당 리포지토리에 설치되었는지
워크플로우가 issue_comment / pull_request_review_comment 이벤트를 듣고 있는지
코멘트가 정확히
@claude를 포함하는지 (/claude와 혼동하지 않기)
CI가 Claude의 커밋에 대해 실행되지 않는다면, GitHub 앱이 아닌 "Actions 사용자"로 커밋하고 있지는 않은지, 그리고 CI 워크플로우의 이벤트 필터가 Claude의 브랜치/커밋에도 적용되는지 확인해야 한다.
인증 에러가 발생할 경우, 직접 API 사용이라면 ANTHROPIC_API_KEY가 올바른지와 권한 상태를 확인하고, Bedrock/Vertex 사용 중이라면 OIDC/Workload Identity 설정과 시크릿 이름(AWS_ROLE_TO_ASSUME, GCP_WORKLOAD_IDENTITY_PROVIDER, GCP_SERVICE_ACCOUNT 등)이 워크플로우에서 정확히 참조되고 있는지 검증해야 한다.
액션 파라미터 전체 구조 한눈에 정리
Claude Code 액션 v1의 주요 입력 파라미터는 다음 네 축으로 이해하면 된다.
첫째, 인증 관련:
anthropic_api_key: Claude API 직접 사용 시 필수github_token: GitHub API 접근용 토큰 (앱으로부터 생성한 토큰 사용을 권장)
둘째, 동작 지시:
prompt: 자연어 또는 슬래시 커맨드로 작성된 지시문 (이슈/PR 멘션 대응에는 필수는 아님)trigger_phrase: 기본은@claude이지만, 필요하면 다른 문구로 변경 가능
셋째, 실행 옵션:
claude_args: 모든 상세 CLI 옵션 전달 창구 (--max-turns,--model,--mcp-config,--allowed-tools,--debug등)
넷째, 백엔드 선택:
use_bedrock:"true"일 경우 AWS Bedrock 사용use_vertex:"true"일 경우 Google Vertex AI 사용
이 네 축을 조합해 "어떤 이벤트에, 어떤 지시로, 어떤 백엔드 모델을, 어떤 옵션으로" 실행할지 설계하는 방식이다.
인사이트
Claude Code GitHub Actions를 잘 활용하면 "코드 리뷰·리팩터링·버그 수정·리포트 작성" 같은 반복적 개발 작업을 상당 부분 자동화할 수 있다.
단, 마법처럼 "모든 문제를 대신 해결해 주는" 도구라기보다는, 잘 설계된 프롬프트와 워크플로우, 그리고 적절한 가드레일(CLAUDE.md, 권한·비용 관리)이 있어야 진짜 생산성 향상이 나온다.
실무에서 시작해 보려면 다음 순서를 추천한다.
가장 단순한
@claude멘션 대응 워크플로우를 만들고, 수동 코드 리뷰·작은 버그 수정부터 맡겨 본다.프로젝트에 맞는
CLAUDE.md를 작성해 점점 팀 규칙을 반영한다./review,/fix같은 슬래시 커맨드를 활용해 PR 오픈 시 자동 리뷰 등 반복 업무를 옮겨간다.안정성이 확인되면 Bedrock/Vertex와 연동해 보안·데이터 레지던시 요구까지 충족시키도록 확장한다.
이런 식으로 단계를 밟으면, 개발팀의 실질적인 부담은 줄이면서도 품질과 일관성은 오히려 높이는 방향으로 Claude를 도입할 수 있다.