Quick Reference
Claude Code GitHub Action은 개발자 컴퓨터가 아니라 GitHub Actions runner에서 실행됩니다. PR·issue 댓글의 @claude에 반응시키는 흐름은 사람이 시작 시점을 정할 때, prompt 기반 workflow는 정기 점검·자동 리뷰처럼 trigger가 분명할 때 맞습니다. 실행이 자동이라는 뜻은 merge 승인을 대신한다는 뜻이 아니므로, 결과 검토와 GitHub token 권한은 별도로 설계합니다.
| 작업 성격 | 시작 방식 | 최소 확인 |
|---|---|---|
| 특정 issue·PR에서만 도움 요청 | @claude mention | 호출자 권한, 대상 repository, bot의 쓰기 범위 |
| 모든 내부 PR의 read-only 리뷰 | pull_request + prompt | contents: read, 필요한 경우에만 pull-requests: write |
| 주기적 문서·의존성 점검 | schedule + 명시 prompt | branch, 시간·비용 상한, 결과 전달 위치 |
| 수정 PR 생성 | 명시 prompt 또는 mention | branch 정책, contents write, test·review·merge ownership |
| fork·외부 댓글을 다룸 | 공식 claude-code-action | untrusted input과 secrets가 섞이지 않게 trigger·checkout을 검토 |
GitHub event / comment
-> GitHub Actions runner에서 workflow 시작
-> action이 repository, prompt, token, Claude 인증을 사용
-> comment / review / branch 변경 결과 생성
-> 사람이 diff, CI, 권한, merge를 검토최소 권한 workflow
name: Claude PR review
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
pull-requests: write
jobs:
review:
if: github.event.pull_request.head.repo.fork == false
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: >-
Review this pull request for correctness and security risks.
Do not edit files, commit changes, or merge the pull request.
claude_args: --max-turns 8prompt는 맡길 작업과 금지 범위를 적는 곳이고, claude_args는 model·turn·permission mode 같은 Claude Code 실행 옵션을 전달하는 곳입니다. pull-requests: write는 review comment를 게시할 때만 필요합니다. 읽기 결과를 workflow summary나 외부 artifact로만 남긴다면 이 권한도 제거할 수 있습니다. 반대로 코드 수정과 push를 허용하려면 contents: write가 필요해지므로 review workflow와 분리하는 편이 안전합니다.
Claude API key는 workflow 파일에 직접 쓰지 않고 GitHub Secrets로 주입합니다. static key 대신 workload identity federation을 쓸 수 있는 환경이라면 short-lived credential을 검토합니다. /install-github-app quick setup은 GitHub App 설치와 secret 설정을 돕지만, repository admin 권한과 App이 요청하는 Contents·Issues·Pull requests 권한을 확인한 뒤 실행합니다.
trigger와 신뢰 경계
PR title·comment·issue 본문·fork의 코드와 .claude/ 설정 파일은 모두 workflow에 들어올 수 있는 외부 입력입니다. 이 입력에 secret 또는 write-capable GITHUB_TOKEN을 함께 주면 prompt injection이 repository 변경이나 data exposure로 이어질 수 있습니다. untrusted input을 처리할 때는 단순 runner wrapper보다 actor permission check와 base ref configuration 복원을 제공하는 공식 anthropics/claude-code-action을 사용하고, trigger와 checkout target을 따로 검토합니다.
| trigger | 적합한 일 | 특히 조심할 점 |
|---|---|---|
issue_comment | 허용된 사용자의 @claude 요청 | comment 본문은 신뢰하지 않고 호출자 권한을 검사합니다. |
pull_request | fork 포함 read-only 검사 | secrets·write token의 이용 가능 범위와 결과 게시 권한을 분리합니다. |
pull_request_target | base repository 문맥의 제한된 관리 작업 | untrusted PR head를 checkout하거나 실행하면 안 됩니다. |
schedule | 반복되는 점검 | default branch, concurrency, 비용 상한, 실패 알림을 명시합니다. |
workflow_dispatch | 사람이 시작하는 운영 작업 | 입력값 검증과 실행자 권한을 확인합니다. |
claude-code-base-action은 Claude Code를 실행하는 얇은 wrapper로, working directory의 CLAUDE.md, .claude/, .mcp.json을 그대로 읽습니다. untrusted branch·comment·configuration을 다뤄야 한다면 base action으로 직접 조합하지 말고, 해당 경계를 처리하는 공식 action을 우선 사용합니다.
결과를 운영에 반영하는 법
Action이 생성한 comment, review, commit, PR은 제안 또는 작업 산출물입니다. 조건을 통과한 CI, code owner review, 사람이 확인한 diff가 merge 기준을 대신하지 않습니다. 자동 수정과 review-only는 token 권한·prompt·branch 규칙·workflow 파일을 분리하고, 한 workflow가 상황에 따라 write를 얻지 않도록 구성합니다.
review-only
contents: read -> finding 게시 -> 사람이 수정·merge
implementation
제한된 branch -> test 실행 -> PR 생성 -> reviewer 승인 -> mergeCLAUDE.md와 repository skill은 action에도 적용될 수 있지만, 이를 security control로 보지 않습니다. 실제 차단은 GitHub token permission, branch protection, secret 노출 범위, runner 격리, action의 actor 검증에서 이뤄져야 합니다.
참고 링크
3 sources