Claude Code를 GitHub Actions에 통합하기 — PR 리뷰와 정형 작업을 CI에서 자동화하기

Claude Code는 로컬 터미널에서 사용하는 것이라고 생각하기 쉽지만, GitHub Actions에 통합하여 CI(지속적 통합) 내에서 실행할 수도 있습니다. 이를 통해 다음과 같은 작업들을 자동화할 수 있습니다.

• Pull Request(PR)에 @claude라고 댓글을 달면 Claude가 대응함
• PR이 생성될 때마다 자동으로 코드 리뷰(Code Review)가 실행됨
• 매일 아침 정해진 시간에 전날의 커밋(Commit)이나 이슈(Issue)의 요약(Summary)을 생성함

이 기사에서는 공식 claude-code-action을 사용한 통합 방법을 최소 구성부터 실용 사례까지 정리합니다.

주의: GitHub Actions 연동 액션(Action)의 이름 및 입력 파라미터(Input Parameter)는 변경될 수 있습니다. 본 기사는 집필 시점(2026년 6월)의 공식 문서를 참조하고 있으나, 도입 시에는 최신 문서를 직접 확인하시기 바랍니다. 또한, CI 상에서 Claude를 실행하면 API 이용 요금이 발생합니다. 트리거(Trigger) 조건, 실행 횟수, 모델(Model)을 고려하여 비용을 의식하며 설계해 주세요.

GitHub Actions에서 Claude Code를 실행하려면 공식 anthropics/claude-code-action@v1을 워크플로(Workflow)에 추가합니다. API 키는 GitHub의 Secret으로 전달합니다.

기본 형태는 다음과 같습니다.

- uses: anthropics/claude-code-action@v1
with:
  anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
...

• anthropic_api_key: API 키. 리포지토리(Repository)의 Secret에 ANTHROPIC_API_KEY로 등록하여 전달
• prompt: Claude에게 주는 지시(생략 가능. 댓글 기반인 경우 없어도 됨)
• claude_args: Claude Code의 CLI 인자(Argument) (--max-turns나 --model 등)

워크플로에 API 키를 직접 작성하는 것은 엄격히 금지됩니다. GitHub 리포지토리의 Settings → Secrets and variables → Actions에서 ANTHROPIC_API_KEY를 등록하고, 워크플로에서는 ${{ secrets.ANTHROPIC_API_KEY }}로 참조합니다.

주의: API 키를 워크플로 파일이나 로그에 평문으로 노출하지 마세요. 반드시 Secret을 통해서만 전달해야 합니다.

가장 심플한 구성은 Issue 댓글이나 리뷰 댓글에서 @claude라고 멘션(Mention)하면 반응하는 구성입니다. 공식 문서의 최소 예시입니다.

name: Claude Code
on:
  issue_comment:
    ...

이를 설정해 두면, PR이나 Issue의 댓글로 "@claude 이 버그의 원인을 조사해줘"와 같이 요청하는 것만으로 CI 상의 Claude가 작동합니다. 로컬을 떠나 있어도 브라우저를 통해 지시할 수 있다는 것이 장점입니다.

Pull Request의 오픈(Open) 및 업데이트를 트리거로 하여 자동 리뷰를 실행하는 구성입니다. 공식 문서에는 플러그인(Plugin) 스킬을 호출하는 예시가 있습니다.

name: Code Review
on:
  pull_request:
    ...

• on: pull_request의 opened / synchronize: PR 생성 시와 커밋 추가 시에 발화(Trigger)
• plugins: 리뷰용 스킬을 로드
• prompt: 해당 스킬을 PR 번호와 함께 호출

PR마다 자동으로 리뷰 댓글이 달리는 운용 방식이 됩니다. 다만 모든 PR에서 매번 실행되면 비용이 누적되므로, 대상 브랜치(Branch)나 라벨(Label)로 범위를 좁히는 것을 검토하십시오.

schedule 트리거를 사용하면 cron을 통해 정기적으로 실행할 수 있습니다. 공식 문서의 예시입니다.

name: Daily Report
on:
  schedule:
    ...

cron: "0 9 * * *"로 매일 특정 시각에 실행됩니다 (GitHub Actions의 cron은 UTC 기준이므로, 일본 시간(또는 한국 시간)에 맞춰 작동시키려면 시간을 조정해야 한다는 점에 주의하세요). "전날의 커밋과 오픈된 Issue의 요약을 만든다"와 같은 정형 보고서(Report) 작업에 적합합니다.

CI 상에서 Claude를 실행하면 실행할 때마다 API 이용료가 발생합니다. 자동화를 즐겁게 할수록 요금도 쌓이기 때문에, 처음부터 기준선을 정해 두는 것이 안심할 수 있는 방법입니다.

관점	사고 방식
트리거 제한	모든 PR/모든 커밋에서 실행하지 않고, 라벨이나 대상 브랜치로 한정
턴(Turn) 수 제한	claude_args: "--max-turns N"으로 폭주 방지
모델 구분 사용	가벼운 정형 작업은 경량 모델, 무거운 작업만 고성능 모델로
우선 수동 검증	자동 트리거로 만들기 전에, workflow_dispatch 등으로 수동 실행하여 동작 확인

특히 턴(Turn) 수의 상한은 안전장치로서 유효합니다. 예상치 못하게 길게 작동하여 비용과 CI 시간을 잡아먹는 사고를 방지할 수 있습니다.

• 공식 액션
  anthropics/claude-code-action@v1

• GitHub Actions에 통합 가능

• API 키는 반드시 Secret (ANTHROPIC_API_KEY)을 통해 전달

• 주요 사용법: ① 댓글로 @claude 호출 ② PR 자동 리뷰 ③ 스케줄에 따른 정기 리포트

• CI에서 실행하면 API 비용이 발생합니다. 트리거, 턴 수, 모델로 비용을 관리하세요.

우선은 "댓글로 @claude를 호출할 수 있는" 최소 구성부터 도입하여, 동작과 비용 체감을 파악한 뒤 자동 리뷰나 스케줄 실행으로 확장하는 것이 안전합니다.

CI에 맡기는 작업일수록 CLAUDE.md에 규칙을 명문화하고, 리뷰 관점이나 진행 방식을 템플릿화해 두면 자동 실행에서도 일관된 품질을 유지하기 쉬워집니다. 제가 사용 중인 스킬을 무료로 공개하고 있습니다.

무료 스타터 (GitHub · CC BY 4.0):

CLAUDE.md 설계 · 계획 우선 개발 (PIV) · AI 커밋 전략 · 애자일(Agile) 프롬프트 설계의 4가지 스킬이 일본어와 영어로 포함되어 있습니다. CI 연동 전에 사람이 리뷰하는 운용 방식으로 형식을 다져두면 원활합니다. 우선 무료 리포지토리부터 시도해 보세요.

최신 팁은 X에서도 발신하고 있습니다: @k___n___t_1125