클로드 코드 GitHub Actions 사용법
클로드 코드를 터미널에서 사용하는 것도 좋지만, GitHub 저장소에 통합해서 팀 전체가 활용할 수 있다면 어떨까요?
PR을 올릴 때마다 Claude가 자동으로 코드를 리뷰하고, 이슈에 @claude를 태그하면 자동으로 수정 PR을 만들어주고, 심지어 매일 밤 자동으로 코드베이스 리포트를 생성할 수도 있습니다. 바로 클로드 코드 GitHub Actions가 가능하게 하는 일들이죠.
이번 글에서는 클로드 코드를 GitHub Actions와 통합해서 AI 기반 워크플로우를 자동화하는 방법을 알아보겠습니다.
클로드 코드 GitHub Actions란?
클로드 코드 GitHub Actions는 Anthropic이 공식 제공하는 GitHub Action으로, GitHub Actions의 워크플로우 내에서 클로드 코드를 실행할 수 있게 해줍니다. 코드 리뷰부터 버그 수정, 기능 구현, 문서 업데이트까지 반복적인 개발 작업을 자동화할 수 있죠.
핵심은 두 가지 작동 방식입니다. 첫째는 상호작용 모드인데요, 이슈나 PR 댓글에 @claude를 태그하면 자동으로 응답합니다. 둘째는 자동화 모드로 PR 제출이나 병합과 같은 특정 이벤트가 발생하면 미리 정의된 프롬프트를 실행하죠.
GitHub Actions 러너에서 실행되기 때문에 코드가 GitHub를 벗어나지 않고 저장소 권한과 시크릿을 안전하게 활용할 수 있습니다.
빠른 시작: 5분 안에 설정하기
가장 쉬운 방법은 클로드 코드 CLI의 설치 명령어를 사용하는 겁니다. 터미널에서 claude를 실행한 후 다음 명령어를 입력하세요.
/install-github-app이 명령어는 대화형으로 다음 단계를 안내해줍니다.
╭────────────────────────────────────────────────────────────────────╮
│ Install GitHub App │
│ Select GitHub repository │
│ │
│ > Use current repository: 소유자/저장소
│ │
│ Enter a different repository │
│ │
╰────────────────────────────────────────────────────────────────────╯
↑/↓ to select · Enter to continue우선 어떤 저장소에 설치할지를 선택하게 됩니다.
╭────────────────────────────────────────────────────────────────────╮
│ Install the Claude GitHub App │
│ │
│ Opening browser to install the Claude GitHub App… │
│ │
│ If your browser doesn't open automatically, visit: │
│ │
│ https://github.com/apps/claude │
│ │
│ Please install the app for repository: DaleStudy/test │
│ │
│ Important: Make sure to grant access to this specific repository │
│ │
│ Press Enter once you've installed the app… │
│ │
│ Having trouble? See manual setup instructions at: https://github.c │
│ om/anthropics/claude-code-action/blob/main/docs/setup.md │
╰────────────────────────────────────────────────────────────────────╯그다음 브라우저가 열리면서 Claude GitHub App을 저장소에 설치하게 됩니다. 저장소의 파일을 읽고 쓸 수 있고 이슈와 PR에도 접근할 수 있는 권한을 요청하죠. GitHub 계정 소유자나 저장소 관리자만 설치할 수 있습니다.
╭────────────────────────────────────────────────────────────────────╮
│ Select GitHub workflows to install │
│ We'll create a workflow file in your repository for each one you │
│ select. │
│ │
│ More workflow examples (issue triage, CI fixes, etc.) at: https:// │
│ github.com/anthropics/claude-code-action/blob/main/examples/ │
│ │
│ ✓ @Claude Code │
│ Tag @claude in issues and PR comments │
│ │
│ ✓ Claude Code Review │
│ Automated code review on new PRs │
╰────────────────────────────────────────────────────────────────────╯
↑↓ to Navigate · Space to toggle · Enter to confirm그다음 설치할 GitHub Actions 워크플로우를 선택할 수 있는데요.
@claude를 태그에 반응하는 워크플로우와 PR이 올라오면 자동으로 코드 리뷰를 해주는 워크플로우를 선택할 수 있습니다.
╭────────────────────────────────────────────────────────────────────╮
│ Install GitHub App │
│ Choose API key │
│ │
│ > Create a long-lived token with your Claude subscription │
│ │
│ Enter a new API key │
│ │
╰────────────────────────────────────────────────────────────────────╯그다음 장기 토큰을 생성하거나 또는 API 키를 입력하라는 안내가 나오는데요. Claude를 구독하고 계시는 분은 장기 토큰을 선택하면 브라우저가 열리고 승인할 수 있습니다. 그러면 발급된 토큰이 저장소의 시크릿(secret)으로 추가됩니다. 구독하시지 않은 분은 Anthropic Console에서 API 키를 발급받아 GitHub 저장소의 Settings → Secrets and variables → Actions에서 추가하면 됩니다.
╭────────────────────────────────────────────────────────────────────╮
│ Install GitHub App │
│ Success │
│ │
│ ✓ GitHub Actions workflow created! │
│ │
│ ✓ API key saved as CLAUDE_CODE_OAUTH_TOKEN secret │
│ │
│ Next steps: │
│ 1. A pre-filled PR page has been created │
│ 2. Install the Claude GitHub App if you haven't already │
│ 3. Merge the PR to enable Claude PR assistance │
╰────────────────────────────────────────────────────────────────────╯
Press any key to exit마지막으로 브라우저가 열리면서 아래 2개의 워크플로우를 추가하는 PR 제출 양식이 뜹니다.
.github/workflows/claude-code-review.yml.github/workflows/claude.yml
이 PR을 승인하고 병합하시면 모든 설정이 완료됩니다.
이제 PR 댓글에 @claude review this code라고 작성하거나 이슈에 @claude implement this feature라고 멘션해보세요. Claude가 자동으로 응답할 겁니다! 🎉
태그 수동 반응 워크플로우
클로드 코드가 워크플로우를 생성해주지만 그 이후 유지보수는 개발자의 몫입니다. 따라서 워크플로우를 어느 정도 이해해두면 도움이 됩니다.
먼저 @claude 태그를 통해서 생성되는 워크플로우는 다음과 같은 구조를 가집니다.
기본적으로 이슈나 PR에 @claude가 포함되어 있는 댓글이 달리면 자동으로 감지 후 응답하게 됩니다.
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]
pull_request_review:
types: [submitted]
jobs:
claude:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
actions: read
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
additional_permissions: |
actions: read워크플로우는 4가지 경우에 실행됩니다. 이슈 댓글에 @claude가 있을 때, PR 리뷰 댓글에 @claude가 있을 때, 이슈 내용이나 이슈의 담당자로 @claude가 할당되었을 때, 마지막으로 PR의 검토자로 @claude를 할당했을 때죠.
anthropics/claude-code-action@v1은 Anthropic이 공식 제공하는 액션입니다. @v1은 메이저 버전을 의미하며 자동으로 최신 마이너/패치 버전을 사용하게 됩니다.
PR 자동 리뷰 워크플로우
PR이 열릴 때마다 Claude가 자동으로 코드 리뷰를 수행하게 하는 워크플로우 파일은 다음과 같은 구조를 가집니다.
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize, ready_for_review, reopened]
jobs:
claude-review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Run Claude Code Review
id: claude-review
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
plugins: 'code-review@claude-code-plugins'
prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'여기서 prompt: "/code-review"는 클로드 코드에 내장된 리뷰 스킬을 실행합니다.
커스텀 프롬프트 활용
클로드 코드 GitHub Actions를 활용하면 저장소의 정기 리포트를 받아볼 수 있습니다. 매일 아침 출근하면 어제 하루 동안의 커밋과 이슈 요약을 확인할 수 있다면 편리하겠죠?
name: Daily Report
on:
schedule:
- cron: "0 0 * * *"
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"cron 스케줄을 사용하면 특정 시각에 자동으로 워크플로우를 실행할 수 있습니다. 여기서는 매일 자정(UTC)에 실행되도록 설정했고 기본 모델인 Sonnet보다 추론 능력이 강력한 Opus 모델을 지정해서 활용했습니다.
모델 변경하기
클로드 코드 GitHub Actions는 기본적으로 Sonnet 모델을 사용합니다. 작업의 난이도에 따라 다른 모델로 바꾸고 싶을 때가 있는데요, claude_args에 --model 옵션을 추가하면 됩니다.
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "이 PR의 보안 취약점을 분석해주세요"
claude_args: "--model opus"사용할 수 있는 모델과 지정 방법은 다음과 같습니다.
| 모델 | 별칭 | 전체 ID |
|---|---|---|
| Haiku 4.5 | haiku | claude-haiku-4-5-20251001 |
| Sonnet 4.5 | sonnet | claude-sonnet-4-5-20250929 |
| Opus 4.6 | opus | claude-opus-4-6 |
별칭(opus, sonnet, haiku)은 항상 해당 모델의 최신 버전을 가리킵니다. 특정 버전에 고정하고 싶다면 전체 ID를 사용하면 돼요.
간단한 코드 포맷팅이나 린트 수정 같은 작업에는 비용이 저렴한 Haiku를, 복잡한 아키텍처 리뷰나 보안 분석에는 Opus를 사용하면 비용과 품질의 균형을 맞출 수 있습니다.
도구 허용/차단하기
클로드 코드는 파일 읽기, 쓰기, 셸 명령 실행 등 다양한 도구를 사용할 수 있는데요, GitHub Actions에서 실행할 때는 어떤 도구를 쓸 수 있는지 제어하고 싶을 때가 있습니다. --allowedTools와 --disallowedTools 옵션으로 이를 관리할 수 있어요.
--allowedTools는 나열한 도구를 별도의 확인 없이 자동으로 허용합니다.
claude_args: '--allowedTools "Read" "Grep" "Bash(git log *)" "Bash(git diff *)"'이렇게 하면 파일 읽기, 코드 검색, git log와 git diff 명령만 자동 승인됩니다.
반대로 --disallowedTools는 나열한 도구를 아예 사용하지 못하게 차단합니다.
claude_args: '--disallowedTools "Write" "Bash(git push:*)"'이렇게 하면 파일 쓰기와 git push 명령이 완전히 차단돼요.
두 옵션을 함께 사용하면 세밀한 권한 정책을 만들 수 있습니다. 예를 들어 코드 리뷰 워크플로우에서는 코드를 읽고 분석만 하고 수정은 못하게 하는 식이죠.
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "이 PR을 리뷰해주세요"
claude_args: |
--model opus
--allowedTools "Read" "Grep" "Bash(git log *)" "Bash(git diff *)"
--disallowedTools "Write" "Bash(git push:*)"사용 가능한 주요 도구 이름은 Bash, Read, Edit, Write, Glob, Grep 등이 있고, Bash(git log *)처럼 괄호 안에 패턴을 넣어 특정 명령만 허용하거나 차단할 수도 있습니다.
유용한 팁
프로젝트 스타일과 규칙을 Claude가 따르게 하려면 어떻게 해야 할까요? 바로 컨텍스트 파일 CLAUDE.md를 저장소 루트에 추가하면 됩니다.
GitHub Actions와 Claude API를 함께 사용하면 두 가지 비용이 발생합니다. GitHub Actions 러너 사용 시간과 Claude API 토큰 사용량이죠.
비용을 절약하려면 다음 전략을 활용하세요. 우선 --max-turns 옵션으로 대화 턴을 제한해서 무한 루프를 방지합니다. 또한 모든 PR이 아닌 특정 파일이나 레이블에만 리뷰를 수행하도록 필터링하고, 간단한 작업에는 Sonnet 대신 Haiku 모델을 사용하는 것도 좋은 방법입니다.
GitHub Actions의 concurrency 설정을 사용하면 동일한 PR에 대해 동시에 여러 워크플로우가 실행되는 걸 방지할 수 있습니다.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true이 설정은 같은 브랜치에 새 커밋이 푸시되면 이전 워크플로우를 취소하고 새로운 워크플로우만 실행합니다.
마치며
클로드 코드 GitHub Actions는 터미널 기반 클로드 코드의 강력함을 팀 전체가 활용할 수 있게 만들어줍니다. PR 리뷰 자동화부터 이슈 자동 수정, 정기적인 코드베이스 리포트 생성까지 다양한 워크플로우를 구축할 수 있죠.
GitHub Actions의 기본 개념을 이해하고 있다면 클로드 코드 Action을 통합하는 건 어렵지 않습니다. 5분이면 기본 설정을 마칠 수 있고 CLAUDE.md 파일로 프로젝트별 맞춤 설정도 가능합니다.
더 자세한 내용은 공식 저장소와 클로드 코드 문서를 참고하세요. 다양한 예제 워크플로우도 제공되니 프로젝트에 맞게 커스터마이징해보세요! 😊
This work is licensed under
CC BY 4.0
