Claude Code GitHub Actions

• Code Review: 워크플로우를 작성하지 않고 모든 풀 리퀘스트에서 자동 리뷰
• 클라우드의 Claude Code: 클라우드 인프라에서 실행되는 Claude Code 세션
• Claude Agent SDK: GitHub Actions 외부의 사용자 정의 자동화. Claude Code GitHub Action은 SDK를 기반으로 구축됩니다
• GitHub Enterprise Server: 자체 호스팅 GitHub를 사용한 Claude Code

​

설정

• 빠른 설정: Claude Code에서 /install-github-app을 실행합니다. Claude Code가 GitHub App을 설치하고, 인증 시크릿을 추가하고, 워크플로 풀 리퀘스트를 준비합니다
• 수동 설정: 앱을 설치하고, 시크릿을 추가하고, 워크플로 파일을 저장소에 직접 복사합니다. 로컬에서 Claude Code를 실행하지 않는 경우, 명령이 실패하는 경우, 또는 워크플로 파일을 완전히 제어하려는 경우에 이 방법을 사용합니다

​

빠른 설정

• Claude Code에 이미 API 키가 있으면 해당 키를 재사용하며, 저장소에 ANTHROPIC_API_KEY 시크릿이 이미 설정되어 있으면 이를 유지할지 묻습니다
• 그렇지 않으면 Claude 구독으로 장기 토큰을 생성할지, API 키를 붙여 넣을지 선택합니다

• /install-github-app을 다시 실행합니다. 저장소에 이미 claude.yml이 있으면 Update workflow file with latest version을 선택합니다. Claude Code는 최초 설치와 마찬가지로 워크플로 파일의 새 사본을 새 브랜치에 푸시하고 풀 리퀘스트를 엽니다.
• 리뷰 워크플로 예제의 --comment 인수와 claude_args 줄을 체크인된 파일에 직접 추가합니다. 이 방법을 사용하면 파일에 적용한 다른 수정 사항이 유지됩니다.

​

수동 설정

​

조직 단위로 설정하기

• 조직 수준에서 Claude GitHub App을 한 번 설치하고, 모든 저장소 또는 선택한 저장소 목록을 지정합니다
• 각 저장소에 별도의 사본이 필요하지 않도록 인증 시크릿을 조직 수준 Actions 시크릿으로 저장합니다
• Claude Code GitHub Action을 실행할 각 저장소에 워크플로 파일을 추가하거나, 각 저장소가 호출하는 재사용 가능한 워크플로로 작업을 한 번 정의합니다

• anthropic_federation_rule_id: 페더레이션 규칙 ID, fdrl_...
• anthropic_organization_id: Anthropic 조직 ID
• anthropic_service_account_id: 서비스 계정 ID, svac_.... Console에서 생성하는 페더레이션 규칙이 이미 서비스 계정을 대상으로 하므로 선택 사항입니다
• anthropic_workspace_id: 워크스페이스 ID, wrkspc_.... 페더레이션 규칙이 단일 워크스페이스를 대상으로 하는 경우 선택 사항입니다

​

제거

• 워크플로 파일: .github/workflows/에서 anthropics/claude-code-action을 사용하는 워크플로를 삭제합니다. 빠른 설정을 사용했다면 claude.yml을 찾고, 리뷰 워크플로를 선택했다면 claude-code-review.yml도 찾습니다. 워크플로를 삭제하면 Claude Code GitHub Action이 더 이상 실행되지 않습니다
• 시크릿: 저장소에서 ANTHROPIC_API_KEY 또는 CLAUDE_CODE_OAUTH_TOKEN 시크릿을 삭제하고, 여러 저장소에서 공유한 경우 조직 수준 Actions 시크릿에서도 삭제합니다. 시크릿을 삭제해도 그 안에 있던 자격 증명은 유효한 상태로 남습니다. API 키를 완전히 폐기하려면 Claude Console에서도 키를 삭제합니다
• GitHub App: 저장소 또는 조직 설정의 GitHub Apps에서 Claude GitHub App을 제거합니다. 단, Code Review나 웹 자동 수정 등 다른 Claude 기능에 사용하지 않는 경우에만 제거합니다

​

GitHub App 권한

​

대화형 및 자동화 모드

• 대화형 모드: 워크플로우가 prompt 입력을 제공하지 않으면 Claude는 트리거 구문인 @claude(기본값)를 이슈나 풀 리퀘스트 댓글, 풀 리퀨스트 리뷰 또는 새로 열린 이슈의 본문이나 제목에서 기다린 후 해당 요청에 응답합니다. 진행 상황과 결과는 트리거 이슈나 PR의 댓글로 나타납니다.
• 자동화 모드: 워크플로우가 prompt 입력을 제공하면 Claude는 실행을 트리거할 수 있는 사람에 대한 확인만 받아 대기 없이 실행됩니다. 기본적으로 결과는 댓글이 아닌 워크플로우 실행 로그에 나타납니다. Claude는 프롬프트가 지시할 때 그리고 코드 리뷰 예제와 같이 게시할 수 있는 도구가 있을 때 이슈나 풀 리퀘스트에 게시할 수 있습니다.

​

실행을 트리거할 수 있는 사람

• 쓰기 액세스: 이슈 및 풀 리퀘스트 이벤트에서 트리거 사용자는 저장소에 대한 쓰기 액세스 권한이 있어야 합니다. 쓰기 액세스 없이 특정 사용자를 허용하려면 allowed_non_write_users를 설정하고 자신의 github_token 입력을 전달합니다. schedule 트리거와 같이 사용자가 작성하지 않은 이벤트는 이 확인을 건너뜁니다.
• 인간 행위자: 모든 이벤트에서 Claude Code GitHub Action은 allowed_bots에 나열하지 않는 한 봇 행위자를 거부합니다. 이는 봇이 루프에서 Claude를 트리거하는 것을 방지합니다. 이 확인은 GitHub가 저장소 사용자(일반적으로 워크플로우의 cron 일정을 마지막으로 변경한 사용자)에 귀속시키는 예약된 실행에도 적용됩니다. 해당 사용자가 봇이면 allowed_bots에 나열합니다.

​

예제 사용 사례

​

@claude 멘션에 응답

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

• id-token: write: Claude Code GitHub Action의 기본 GitHub App 인증에 필요합니다
• actions: read: Claude가 PR에서 CI 결과를 읽을 수 있게 합니다
• actions/checkout: Claude에게 작업할 저장소의 로컬 복사본을 제공합니다
• if: @claude를 멘션하지 않는 댓글에서 러너가 시작되지 않도록 합니다. Claude Code GitHub Action도 응답하기 전에 트리거 구문 자체를 확인합니다

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

​

스킬 실행

• 저장소의 .claude/skills/ 디렉토리에 있는 스킬의 경우 anthropics/claude-code-action 단계 전에 actions/checkout을 실행하여 스킬 파일을 러너에서 사용할 수 있게 한 후 /skill-name을 prompt로 전달합니다.
• 플러그인에 패키징된 스킬의 경우 plugin_marketplaces 및 plugins 입력으로 플러그인을 설치한 후 네임스페이스가 지정된 /plugin-name:skill-name을 prompt로 전달합니다. plugins 입력은 plugin-name@marketplace-name을 사용합니다. 마켓플레이스 이름은 저장소 URL이 아닌 마켓플레이스 자체의 매니페스트에서 나옵니다.

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-plugins-official.git"
          plugins: "code-review@claude-plugins-official"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

• --comment: Claude가 풀 리퀘스트에 리뷰를 게시합니다. 발견한 각 이슈에 대한 인라인 댓글로 또는 발견하지 못한 경우 하나의 요약 댓글로 게시합니다. 없으면 Claude는 아무것도 게시하지 않으며 워크플로우 실행 로그에서 결과를 읽습니다.
• claude_args: 스킬 자체의 allowed-tools frontmatter가 동일한 도구를 명명하더라도 이 줄을 유지합니다. Claude Code GitHub Action이 claude_args의 --allowedTools가 이를 명명할 때만 인라인 댓글을 게시하는 MCP 서버를 시작하기 때문입니다.

​

일정에 따라 실행

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    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-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

​

모범 사례

​

CLAUDE.md에서 프로젝트 표준 정의

​

자격 증명 보호

​

비용 관리

• GitHub Actions 분: Claude Code GitHub Action은 GitHub 호스팅 러너에서 실행되며, GitHub Actions 분을 소비합니다. 가격 책정 및 분 제한은 GitHub의 청구 설명서를 참조하십시오.
• API 토큰: 각 상호 작용은 프롬프트 및 응답의 길이, 작업 복잡도 및 코드베이스 크기에 따라 토큰을 소비합니다. 현재 토큰 요금은 Claude의 가격 책정 페이지를 참조하십시오. OAuth 토큰으로 인증하면 실행이 API 청구 대신 Claude 구독을 사용합니다.

• 특정 @claude 요청을 작성하여 Claude가 완료하는 데 더 적은 턴이 필요하도록 합니다
• 이슈 템플릿을 사용하여 미리 컨텍스트를 제공합니다
• CLAUDE.md를 간결하게 유지합니다. Claude가 모든 실행에서 이를 읽기 때문입니다
• claude_args에서 --max-turns를 설정하여 반복을 제한합니다
• 워크플로우 수준 타임아웃을 설정하여 실행 중인 작업을 방지합니다
• GitHub의 동시성 제어를 사용하여 병렬 실행을 제한합니다

​

클라우드 공급자 사용

• Amazon Bedrock: use_bedrock: "true"
• Google Cloud의 Agent Platform: use_vertex: "true"
• Microsoft Foundry: use_foundry: "true"

​

문제 해결

​

Claude가 @claude 명령에 응답하지 않음

• GitHub App이 저장소에 설치되었는지 확인합니다
• 저장소에 대해 워크플로우가 활성화되었는지 확인합니다
• API 키나 OAuth 토큰이 저장소 시크릿에 설정되었는지 확인합니다
• 댓글에 /claude나 @claude-bot이 아닌 완전한 단어로 @claude가 포함되어 있는지 확인합니다
• 댓글 작성자가 저장소에 대한 쓰기 액세스 권한이 있는지 확인합니다. 실행을 트리거할 수 있는 사람에서 예외를 참조하십시오

​

Claude의 커밋에서 CI가 실행되지 않음

• GitHub는 기본 GITHUB_TOKEN으로 만든 커밋에서 워크플로우를 트리거하지 않습니다. Claude Code GitHub Action에 github_token: ${{ secrets.GITHUB_TOKEN }}을 전달하면 Claude GitHub App으로 인증하도록 제거하거나 대신 사용자 정의 앱 토큰을 전달합니다
• CI 워크플로우의 트리거에 Claude의 푸시가 생성하는 이벤트(예: push 또는 pull_request)가 포함되어 있는지 확인합니다

​

인증 오류

• 워크플로우를 디버깅하기 전에 로컬에서 claude로 테스트하여 API 키나 OAuth 토큰이 유효한지 확인합니다
• Bedrock, Agent Platform 및 Foundry의 경우 클라우드 공급자 페이지의 문제 해결 섹션을 참조하십시오

​

고급 구성

​

작업 파라미터

​

CLI 인수 전달

claude_args: "--max-turns 5 --model claude-sonnet-5 --mcp-config /path/to/config.json"

• --max-turns: 대화 턴 수 제한
• --model: 사용할 모델. 예: claude-sonnet-5. 이 인수 없으면 Claude Code GitHub Action이 Claude Code 기본 모델을 사용합니다
• --mcp-config: MCP 구성 경로
• --allowedTools: 허용된 도구의 쉼표로 구분된 목록. --allowed-tools 별칭도 작동합니다
• --debug: 디버그 출력 활성화

​

베타에서 업그레이드

1. uses 줄에서 @beta를 @v1로 변경합니다
2. mode 입력을 제거합니다. Claude Code GitHub Action이 이제 모드를 자동으로 감지하기 때문입니다
3. direct_prompt를 prompt로 바꿉니다
4. max_turns 및 model과 같은 CLI 옵션을 claude_args로 이동합니다. custom_instructions는 같은 이름의 플래그가 없으며 --append-system-prompt가 됩니다

​

다음 단계

• 클라우드 공급자와 함께 Claude Code GitHub Actions 사용: Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 통해 추론을 라우팅합니다
• 구성 참조: 작업 입력의 전체 목록
• Examples 디렉토리: 더 많은 시나리오에 대한 즉시 사용 가능한 워크플로우
• Code Review: 워크플로우 파일을 유지하지 않고 자동 풀 리퀘스트 리뷰