클로드 코드 깃허브 연동 — @claude 멘션으로 PR 만들기
클로드 코드를 깃허브에 붙이면 이슈나 PR 댓글에 @claude라고 부르는 것만으로 코드를 고치고 PR까지 올려 줍니다. 붙이는 방법은 클로드 코드를 켠 상태에서 /install-github-app을 치는 것이고, 이건 터미널 명령이 아니라 세션 안에서 쓰는 슬래시 명령입니다. 이 명령이 GitHub App 설치, 워크플로 파일 추가, API 키 시크릿 등록까지 순서대로 안내합니다. 저장소 관리자 권한이 필요하고, 안 되면 손으로 해도 3단계면 끝납니다. 아래에 설치 순서, 워크플로 예시, 베타에서 올라올 때 반드시 고쳐야 하는 항목까지 정리했습니다. (2026년 8월 2일 기준 · CLI 2.1.204 · 액션 v1)
1. 자동 설치 — /install-github-app
가장 빠른 길입니다. 프로젝트 폴더에서 클로드 코드를 켜고 아래를 칩니다.
/install-github-appclaude install-github-app이라고 치면 안 됩니다. 그런 CLI 명령은 없습니다. 실제로 claude --help를 보면 하위 명령은 agents · auth · auto-mode · doctor · gateway · install · mcp · plugin · project · setup-token · ultrareview · update뿐입니다(2.1.204 기준). 클로드 코드를 켠 다음 대화창에서 슬래시로 치세요.
명령을 치면 GitHub App을 저장소에 설치하고, 이어서 워크플로 파일과 API 키 시크릿을 넣을지 물어봅니다. CLI 2.1.187부터는 Skip for now를 골라 앱 설치까지만 하고 멈출 수 있고, 나중에 같은 명령을 다시 쳐서 이어서 하면 됩니다.
2. 손으로 붙이기 — 3단계
명령이 실패하거나 회사 저장소 정책상 직접 해야 한다면 순서는 이렇습니다.
| 단계 | 할 일 |
|---|---|
| ① 앱 설치 | github.com/apps/claude에서 대상 저장소에 설치 |
| ② 키 등록 | 저장소 Secrets에 ANTHROPIC_API_KEY 추가 |
| ③ 워크플로 | .github/workflows/에 워크플로 YAML 파일 추가 |
이때 앱이 요구하는 저장소 권한은 Contents · Issues · Pull requests 각각 읽기/쓰기입니다. 파일을 고치고, 이슈에 답하고, PR을 만들어 푸시해야 하니 셋 다 필요합니다.
3. 워크플로 파일 — 이것만 있으면 된다
가장 기본형입니다. 이슈 댓글과 PR 리뷰 댓글에 반응합니다.
name: Claude Code
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 }}anthropics/claude-code-action은 Anthropic이 직접 관리하는 공식 액션입니다(2026년 8월 2일 기준 별 8,518개, 최신 릴리스 태그 v1). 어떤 리포가 공식이고 어떤 게 아닌지 헷갈린다면 클로드 깃허브 인기 오픈소스 정리도 참고하세요.
멘션 없이 일정에 맞춰 자동으로 돌리고 싶으면 prompt를 주면 됩니다.
name: Daily Report
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: "어제 커밋과 열린 이슈를 요약해 줘"
claude_args: "--model opus"4. 쓸 수 있는 입력값 정리
| 입력 | 하는 일 |
|---|---|
anthropic_api_key |
Claude API 키 (사실상 필수) |
prompt |
시킬 일. 평범한 문장도, /스킬이름 형태도 됩니다 |
claude_args |
CLI 옵션을 그대로 넘김 (--model, --allowedTools 등) |
trigger_phrase |
부르는 말 바꾸기 (기본값 @claude) |
plugins · plugin_marketplaces |
실행 전에 설치할 플러그인과 그 출처 |
github_token · use_bedrock |
토큰 직접 지정 · Bedrock 사용 여부 |
플러그인을 워크플로에서 설치할 수도 있습니다. 플러그인·마켓플레이스 개념이 낯설면 클로드 코드 플러그인 설치를 먼저 보고 오세요.
5. 베타에서 올라왔다면 반드시 고칠 것
예전 @beta 설정을 그대로 두면 v1에서 동작하지 않습니다. 옛 블로그 글을 보고 따라 했다면 여기서 막힐 가능성이 큽니다.
| 베타 때 쓰던 것 | v1에서는 |
|---|---|
@beta |
@v1 |
mode: "tag" / "agent" |
삭제 (자동으로 판단합니다) |
direct_prompt |
prompt |
custom_instructions |
claude_args: --append-system-prompt |
max_turns · model · allowed_tools |
전부 claude_args 안으로 |
6. 불렀는데 대답이 없을 때
공식 문서가 짚는 원인은 네 가지입니다. 위에서부터 확인하세요.
- 부르는 말이 틀렸다 —
@claude여야 합니다./claude는 안 먹습니다. - GitHub App이 그 저장소에 설치되지 않았다 — 계정에만 설치하고 저장소를 안 고른 경우가 흔합니다.
- Actions가 꺼져 있다 — 저장소 설정에서 워크플로 실행이 켜져 있는지 봅니다.
- 시크릿이 없거나 이름이 다르다 —
ANTHROPIC_API_KEY철자를 확인합니다.
또 하나, 클로드가 만든 커밋에 CI가 안 도는 문제가 있습니다. 기본 Actions 사용자로 푸시하면 깃허브가 워크플로를 다시 트리거하지 않기 때문입니다. GitHub App(또는 별도 앱)으로 푸시되도록 두는 게 해결책입니다.
자주 묻는 질문 (FAQ)
Q. 코드가 Anthropic 서버로 넘어가나요?
액션은 깃허브 러너 위에서 돕니다. 별도 서버로 저장소를 통째로 보내는 구조가 아닙니다. 다만 모델에 보내는 프롬프트에는 작업에 필요한 코드가 포함되므로, 민감한 저장소라면 claude_args로 도구를 좁히는 편이 안전합니다.
Q. 프로젝트 규칙을 지키게 하려면요?
저장소 루트의 CLAUDE.md를 그대로 따릅니다. 코딩 컨벤션·리뷰 기준을 여기 적어 두면 액션에서도 적용됩니다. 쓰는 법은 claude.md 작성법에 정리해 뒀습니다.
Q. 멘션 없이 모든 PR을 자동 리뷰하게 하고 싶습니다.
on: pull_request로 트리거를 걸고 prompt를 주면 됩니다. 위 Daily Report 예시와 같은 방식입니다.
Q. 요금은 어떻게 나가나요?
두 군데서 나갑니다 — 깃허브 액션 실행 시간과 Claude API 토큰 사용량입니다. 멘션마다 도는 구조라, 트리거를 넓게 걸어 두면 생각보다 빨리 쌓입니다.
마무리
정리하면 세션 안에서 /install-github-app 한 번이면 앱 설치부터 워크플로까지 끝납니다. 손으로 한다면 앱 설치 → ANTHROPIC_API_KEY 시크릿 → .github/workflows/에 YAML 세 단계입니다. 옛 글을 보고 따라 하다 막혔다면 @beta 설정을 v1 형식으로 고쳤는지부터 확인하세요.
📚 참고 출처 (2026년 8월 2일 확인)
· Claude Code — Claude Code GitHub Actions
· anthropics/claude-code-action (GitHub)
· CLI 명령 목록과 액션 리포·태그 실재 여부는 claude --help(2.1.204)와 GitHub API로 직접 확인했습니다.
COMMENTS