Claude Code GitHub Actions

Claude Code GitHub Actions

Claude Code GitHub Actions는 리포지토리 워크플로우 안에서 Claude Code를 실행하는 GitHub Action이에요. 풀 리퀘스트나 이슈 댓글에서 @claude를 멘션하면 Claude가 코드를 분석하고 변경을 구현한 뒤 커밋을 푸시합니다. 어떤 GitHub 이벤트에서든 자동으로 실행시킬 프롬프트를 줄 수도 있어요. 이슈를 풀 리퀘스트로 만들거나, 댓글에서 버그를 고치거나, 반복 작업을 자동화하는 데 씁니다.

출처: 공식문서

본문

Claude Code라는 이름을 쓰는 제품은 여러 개입니다. 이 페이지는 리포지토리의 워크플로우 파일로 설정하는 claude-code-action 워크플로우 통합을 다룹니다. 관련 제품은 각각 다음을 참고하세요.

• Code Review: 워크플로우 작성 없이 매 풀 리퀘스트마다 자동 리뷰
• 웹의 Claude Code: 브라우저나 휴대폰에서 쓰는 Claude Code 세션
• Claude Agent SDK: GitHub Actions 밖의 커스텀 자동화. Claude Code GitHub Action은 이 SDK 위에 만들어졌습니다.
• GitHub Enterprise Server: 셀프 호스트 GitHub에서 쓰는 Claude Code

설치 (Setup)

Claude Code GitHub Action은 두 가지 방식으로 설정할 수 있습니다.

• 빠른 설정: Claude Code에서 /install-github-app를 실행. Claude Code가 GitHub App을 설치하고 인증 시크릿을 추가하며 워크플로우 풀 리퀘스트까지 준비해 줍니다.
• 수동 설정: 앱을 설치하고 시크릿을 추가하고 워크플로우 파일을 직접 리포지토리에 복사. Claude Code를 로컬에서 실행하지 않거나, 명령이 실패하거나, 워크플로우 파일을 완전히 제어하고 싶을 때 이 경로를 씁니다.

어느 경로든 리포지토리에 대한 관리자(admin) 접근이 필요합니다.

빠른 설정 (Quick setup)

/install-github-app는 github.com 리포지토리에서만 동작합니다. git 리모트가 gitlab.com이나 bitbucket.org면 설정을 시작하는 대신 안내를 출력하고 종료합니다. GitLab 파이프라인에서 Claude Code를 실행하려면 Claude Code GitLab CI/CD를 참고하세요.

시작 전에 GitHub CLI를 설치하고 gh auth login으로 인증하세요. Claude Code가 이를 확인하고 없으면 경고합니다.

연결하려는 리포지토리에서 claude를 열고 /install-github-app를 실행한 뒤 프롬프트를 따르세요. Claude Code가 Claude GitHub App을 설치한 다음 워크플로우용 인증 시크릿을 설정합니다.

• 이미 API 키가 있으면 그 키를 재사용하고, 이미 설정된 리포지토리의 ANTHROPIC_API_KEY 시크릿이 있으면 유지할지 제안합니다.
• 그렇지 않으면 Claude 구독으로 장기(long-lived) 토큰을 만드는 방법과 API 키를 붙여 넣는 방법 중 하나를 고릅니다.

Claude Code는 자격 증명을 리포지토리 시크릿으로 저장하는데, API 키면 ANTHROPIC_API_KEY, 구독 토큰이면 CLAUDE_CODE_OAUTH_TOKEN 이름을 씁니다.

그다음 Claude Code는 선택한 워크플로우 파일이 담긴 브랜치를 푸시하고(이미 그 시크릿을 쓰도록 설정됨), 브라우저에서 GitHub를 열어 생성할 풀 리퀘스트를 준비합니다. 그 풀 리퀘스트를 만들어 머지하면 리포지토리에서 @claude가 동작합니다.

리뷰 워크플로우를 선택했다면 Claude는 각 리뷰를 풀 리퀘스트 자체에 게시합니다. 발견한 각 이슈에 인라인 댓글로, 아무것도 찾지 못하면 요약 댓글 하나로 답니다. Claude는 드래프트 같은 일부 풀 리퀘스트를 건너뜁니다. 리뷰 워크플로우 예시는 같은 스킬을 쓰고 그 목록을 보여줍니다. v2.1.229 이전에는 Claude가 리뷰를 워크플로우 실행 로그에만 작성했습니다.

이전 버전이 만든 리뷰 워크플로우를 업데이트하려면 다음 중 하나를 하세요.

• /install-github-app를 다시 실행. 리포지토리에 이미 claude.yml이 있으면 Update workflow file with latest version을 선택하세요. Claude Code가 첫 설치처럼 워크플로우 파일의 새 복사본을 새 브랜치로 푸시하고 풀 리퀘스트를 엽니다.
• 리뷰 워크플로우 예시의 --comment 인자와 claude_args 줄을 체크인된 파일에 직접 추가. 이렇게 하면 기존에 만든 다른 편집이 유지됩니다.

GitHub App을 설치한 뒤 Claude Code는 GitHub Actions 설정을 계속할지 묻습니다. Skip for now를 고르면 GitHub App만 설치된 상태로 멈춥니다. 나중에 /install-github-app를 다시 실행해 워크플로우와 시크릿 단계를 마무리하세요. v2.1.187 이전에는 Claude Code가 바로 워크플로우 선택으로 진행했습니다.

* GitHub App을 설치하면 여러 권한을 부여합니다. 전체 목록은 [GitHub App 권한](#github-app-permissions)을 참고하세요. * 빠른 설정은 Claude API와 Claude 구독에서 동작합니다. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry를 쓴다면 [클라우드 제공자와 함께 Claude Code GitHub Actions 사용](/docs/en/github-actions-cloud-providers)을 참고하세요.

수동 설정 (Manual setup)

/install-github-app를 실행하지 않고 Claude Code GitHub Action을 구성하려면 앱을 설치하고 시크릿을 추가하고 워크플로우 파일을 직접 복사하세요.

Step 1: Claude GitHub App 설치 — Claude GitHub App을 리포지토리에 설치하세요. Claude Code GitHub Action은 앱 권한 세 개에 의존합니다.

• Contents: 읽기/쓰기, Claude가 리포지토리 파일을 수정할 수 있도록
• Issues: 읽기/쓰기, Claude가 이슈에 응답할 수 있도록
• Pull requests: 읽기/쓰기, Claude가 PR을 만들고 변경을 푸시할 수 있도록

설치 중에 다른 Claude 기능이 쓰는 권한도 부여합니다. 전체 목록은 GitHub App 권한을 참고하세요.

Step 2: 인증 시크릿 추가 — 인증 방식에 따라 다음 시크릿 중 하나를 리포지토리에 추가하세요. GitHub의 GitHub Actions에서 시크릿 사용 가이드를 참고하세요.

• ANTHROPIC_API_KEY: Claude Console의 Claude API 키
• CLAUDE_CODE_OAUTH_TOKEN: Claude 구독으로 인증하는 OAuth 토큰. Pro, Max, Team, Enterprise 플랜에서 사용 가능. 로컬에서 claude setup-token을 실행해 생성. 장기 토큰 생성 참고.

워크플로우 파일에서는 시크릿을 대응 입력에 전달합니다. API 키면 anthropic_api_key, OAuth 토큰이면 claude_code_oauth_token.

Step 3: 워크플로우 파일 복사 — examples/claude.yml을 리포지토리의 .github/workflows/ 디렉토리로 복사하세요. 이 파일은 예시가 아니라 동작하는 워크플로우입니다. 커밋된 그대로, 누군가 이슈나 풀 리퀘스트에서 @claude를 멘션하면 ANTHROPIC_API_KEY 시크릿으로 인증해 응답합니다. CLAUDE_CODE_OAUTH_TOKEN을 추가했다면 워크플로우의 anthropic_api_key 줄을 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}로 바꾸세요.

설정 후 이슈나 PR 댓글에서 `@claude`를 태그해 Claude Code GitHub Action을 테스트해 보세요.

조직 설정 (Set up for an organization)

빠른 설정이든 수동 설정이든 한 번에 한 리포지토리를 구성합니다. 조직 전체로 Claude Code GitHub Action을 확산시키려면:

• Claude GitHub App을 조직 수준에서 한 번 설치하되, 모든 리포지토리 또는 선택한 목록을 고르세요.
• 인증 시크릿을 조직 수준 Actions 시크릿으로 저장해 각 리포지토리가 자기 사본을 가질 필요가 없게 하세요.
• Claude Code GitHub Action을 실행할 각 리포지토리에 워크플로우 파일을 추가하거나, 각 리포지토리가 호출하는 재사용 가능한 워크플로우로 작업을 한 번 정의하세요.

리포지토리 간에 공유하는 시크릿에는 OAuth 토큰 대신 Claude Console의 API 키로 인증하세요. OAuth 토큰은 claude setup-token을 실행한 사람의 구독에 묶여 있기 때문입니다.

장기 시크릿 저장을 아예 피하려면 워크로드 아이덴티티 페더레이션(workload identity federation)으로 인증하세요. 이 방식에서는 Claude Code GitHub Action이 워크플로우의 GitHub OpenID Connect(OIDC) 토큰을 Claude Console 서비스 계정을 통한 Claude API 접근으로 교환합니다. 다음 입력을 설정합니다.

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

워크플로우에 id-token: write 권한을 부여하세요. 직접 github_token을 넘기더라도 페더레이션 교환을 위해 Claude Code GitHub Action이 필요한 권한입니다. Console 쪽 구성은 Claude Code GitHub Action의 셋업 가이드를 참고하세요.

보안 검토에서 데이터 처리·보존 질문은 데이터 사용과 보안을 참고하세요.

제거 (Uninstall)

Claude Code GitHub Action을 제거하려면 설치의 각 조각을 되돌리세요.

• 워크플로우 파일: .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 기능에 쓰지 않을 때만 그렇게 하세요.

클라우드 제공자를 구성했다면 AWS_ROLE_TO_ASSUME, GCP_* 시크릿, AZURE_* 시크릿 같은 제공자 시크릿도 삭제하고, 커스텀 GitHub App을 APP_ID·APP_PRIVATE_KEY 시크릿과 함께 제거하세요.

GitHub App 권한 (GitHub App permissions)

Claude GitHub App은 GitHub와 통합하는 모든 Claude 기능(Claude Code GitHub Action, Code Review, 웹 Claude Code의 풀 리퀘스트 자동 수정)이 공유합니다. GitHub App은 모든 기능을 아우르는 단일 권한 집합을 가지므로, 그 집합에는 Claude Code GitHub Action이 쓰지 않는 권한도 포함됩니다.

앱을 설치할 때 다음 권한을 부여합니다.

권한	접근
Actions	읽기/쓰기
Checks	읽기/쓰기
Contents	읽기/쓰기
Discussions	읽기/쓰기
Issues	읽기/쓰기
Members	읽기
Metadata	읽기
Pull requests	읽기/쓰기
Repository hooks	읽기/쓰기
Statuses	읽기
Workflows	읽기/쓰기

권한 집합은 그 권한을 쓰는 기능보다 앞서 바뀔 수도 있습니다. 앱이 이전에 없던 권한을 요청하면 GitHub가 계정 소유자에게 승인을 요청합니다(조직 설치는 조직 소유자). 승인할 때까지 설치는 기존 권한을 유지합니다. 예를 들어 Actions 접근이 읽기에서 쓰기로 바뀌면 앱이 실행과 로그를 보는 것만이 아니라 워크플로우를 다시 실행할 수 있게 되므로, GitHub가 소유자에게 그 변경 승인을 요청합니다.

앱을 설치할 때 전체 권한 집합을 수락하게 됩니다. GitHub는 일부만 수락하도록 하지 않습니다. 조직이 Claude Code GitHub Action이 쓰는 권한만 요구한다면 Claude Code GitHub Action의 셋업 가이드를 따라 Contents, Issues, Pull requests만 가진 커스텀 GitHub App을 만드세요. 커스텀 앱은 Claude Code GitHub Action만 다룹니다. Code Review와 웹 자동 수정은 여전히 공식 앱이 필요합니다.

Claude Code GitHub Action이 이 권한으로 Claude가 할 수 있는 일을 어떻게 제한하는지는 보안 문서를 참고하세요.

인터랙티브·자동화 모드 (Interactive and automation modes)

Claude Code GitHub Action은 워크플로우 구성에서 실행 방식을 감지합니다.

• 인터랙티브 모드: 워크플로우가 prompt 입력을 제공하지 않으면 Claude는 이슈·PR 댓글, 풀 리퀘스트 리뷰, 새로 열린 이슈의 본문·제목에서 트리거 문구(기본 @claude)를 기다렸다가 그 요청에 응답합니다. 진행과 결과는 트리거가 된 이슈나 PR의 댓글로 나타납니다.
• 자동화 모드: 워크플로우가 prompt 입력을 제공하면 Claude는 멘션을 기다리지 않고 실행되며, 실행을 트리거할 수 있는 사람에 대한 검사만 적용됩니다. 기본적으로 결과는 댓글 대신 워크플로우 실행 로그에 나타납니다. code-review 예시처럼 프롬프트가 시키고 게시할 수 있는 도구가 있으면 Claude는 이슈나 풀 리퀘스트에 게시할 수 있습니다.

실행을 트리거할 수 있는 사람 (Who can trigger runs)

두 모드 모두에서 Claude Code GitHub Action은 Claude를 시작하기 전에 트리거 액터에 대해 두 가지 검사를 하고, 어느 하나라도 거부하면 실행이 실패합니다.

• 쓰기 접근: 이슈·풀 리퀘스트 이벤트에서 트리거 사용자는 리포지토리에 쓰기 접근이 있어야 합니다. 쓰기 접근 없는 특정 사용자를 허용하려면 allowed_non_write_users와 직접 github_token 입력을 설정하세요. schedule 트리거처럼 어떤 사용자도 만들지 않는 이벤트는 이 검사를 건너뜁니다.
• 사람 액터: 모든 이벤트에서 Claude Code GitHub Action은 봇을 allowed_bots에 나열하지 않는 한 봇 액터를 거부합니다. 이렇게 해서 봇이 Claude를 무한 루프로 트리거하는 것을 막습니다. 이 검사는 예약 실행에도 적용되는데, GitHub는 예약 실행을 리포지토리 사용자(보통 워크플로우 cron 일정을 마지막으로 바꾼 사람)에게 귀속시킵니다. 그 사용자가 봇이라면 allowed_bots에 나열하세요.

예시 사용 사례 (Example use cases)

examples 디렉토리에 시나리오별 바로 쓸 수 있는 워크플로우가 있습니다.

이 페이지의 예시는 API 키 인증을 보여줍니다. Claude 구독으로 인증한다면 어떤 예시의 anthropic_api_key 줄도 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}로 바꾸세요.

@claude 멘션에 응답 (Respond to @claude mentions)

이 워크플로우는 인터랙티브 모드로 Claude Code GitHub Action을 실행하므로, 누군가 이슈나 PR 댓글에서 @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도 응답 전에 트리거 문구 자체를 검사합니다.

워크플로우가 준비되면 요청과 함께 아무 이슈·PR 댓글에서 @claude를 멘션하세요.

@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는 같은 이슈·PR의 댓글로 답하고, 작업하면서 그것을 계속 갱신합니다.

스킬 실행 (Run a skill)

prompt 입력은 평문뿐 아니라 스킬 호출도 받습니다.

• 리포지토리의 .claude/skills/ 디렉토리에 있는 스킬은 anthropics/claude-code-action 단계 전에 actions/checkout을 실행해 러너에 스킬 파일을 준비시킨 뒤 prompt로 /skill-name을 전달하세요.
• 플러그인에 패키징된 스킬은 plugin_marketplaces와 plugins 입력으로 플러그인을 설치한 뒤 네임스페이스된 /plugin-name:skill-name을 prompt로 전달하세요. plugins 입력은 plugin-name@marketplace-name을 받는데, 마켓플레이스 이름은 마켓플레이스 자체 매니페스트에서 오며 리포지토리 URL이 아닙니다.

다음 워크플로우는 풀 리퀘스트가 열리거나, 업데이트되거나, 다시 열리거나, 리뷰 준비 완료로 표시될 때 code-review 플러그인을 설치하고 그 스킬을 실행합니다. 빠른 설정의 리뷰 워크플로우와 같은 플러그인을 실행합니다. 프롬프트·모델·트리거를 직접 제어하고 싶을 때 이런 워크플로우를 쓰세요. 워크플로우 파일 유지 없이 자동 리뷰를 쓰려면 Code Review를 보세요. 공개 리포지토리에서 GitHub는 포크 풀 리퀘스트가 트리거한 실행에는 시크릿을 숨기므로, 리뷰는 같은 리포지토리의 브랜치에서 온 풀 리퀘스트에서만 실행됩니다.

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-code.git"
          plugins: "code-review@claude-code-plugins"
          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이 인라인 댓글을 게시하는 MCP 서버를, claude_args의 --allowedTools가 그 도구를 이름으로 가리킬 때만 시작하기 때문입니다.

Claude는 드래프트·닫힌 풀 리퀘스트, 리뷰가 필요 없다고 판단한 풀 리퀘스트(자동화·사소한 것 등), 이미 Claude 댓글이 있는 풀 리퀘스트를 건너뜁니다.

일정에 맞춰 실행 (Run on a schedule)

prompt 입력으로 Claude Code GitHub Action은 cron 일정을 포함한 어떤 GitHub 이벤트에서도 자동화 모드로 실행됩니다. 평문 프롬프트에서는 Claude가 프롬프트에 필요한 도구를, claude_args의 --allowedTools나 settings 입력의 permissions.allow 규칙으로 부여할 때까지 셸이나 GitHub API 접근이 없습니다. 대신 스킬을 호출하면 Claude는 스킬의 allowed-tools frontmatter가 부여하는 도구를 쓸 수 있습니다. GitHub는 기본 브랜치에서만 예약 워크플로우를 실행하고, 공개 리포지토리에서는 리포지토리 활동이 60일 없으면 일정을 비활성화합니다.

이 워크플로우는 매일 09:00 UTC에 워크플로우 실행 로그에 리포트를 생성합니다. claude_args 줄이 CLI 인자를 전달해 모델을 선택하고 두 GitHub MCP 도구를 허용합니다. Claude는 그 도구로 GitHub API를 통해 커밋과 이슈를 읽으므로 checkout 단계를 생략할 수 있습니다.

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-4-8
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

모범 사례 (Best practices)

CLAUDE.md에 프로젝트 표준 정의 (Define project standards in CLAUDE.md)

리포지토리 루트에 CLAUDE.md 파일을 만들어 코드 스타일 가이드, 리뷰 기준, 프로젝트별 규칙, 선호 패턴을 정의하세요. Claude는 PR을 만들고 요청에 응답할 때 이 가이드라인을 따릅니다. 자세한 내용은 메모리 문서를 참고하세요.

자격 증명 보호 (Protect your credentials)

API 키나 OAuth 토큰을 리포지토리에 직접 커밋하지 마세요. 항상 GitHub Secrets로 저장하고 워크플로우에서 참조하세요. 예: `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}`.

워크플로우에 필요한 권한만 부여하고, 머지 전에 Claude의 변경을 검토하세요.

권한·인증을 포함한 포괄적인 보안 안내는 Claude Code Action 보안 문서를 참고하세요.

비용 관리 (Manage costs)

각 실행은 두 종류의 리소스를 소비합니다.

• GitHub Actions 분(minutes): Claude Code GitHub Action은 GitHub 호스팅 러너에서 실행되며 GitHub Actions 분을 소비합니다. 가격과 분 제한은 GitHub 결제 문서를 참고하세요.
• API 토큰: 각 상호작용이 프롬프트·응답 길이, 작업 복잡도, 코드베이스 크기에 따라 토큰을 소비합니다. 현재 토큰 요율은 Claude 가격 페이지를 참고하세요. OAuth 토큰으로 인증하면 실행이 API 청구 대신 Claude 구독을 사용합니다.

두 비용 모두 Claude에 더 명확한 컨텍스트를 주고 각 실행이 할 수 있는 작업량을 제한해 낮출 수 있습니다.

• 구체적인 @claude 요청을 작성해 Claude가 끝내는 데 필요한 턴을 줄이기
• 이슈 템플릿으로 컨텍스트를 미리 제공
• Claude가 매 실행마다 읽으므로 CLAUDE.md는 간결하게 유지
• claude_args에 --max-turns를 설정해 반복을 제한
• 워크플로우 수준 타임아웃을 설정해 통제 불능 작업 방지
• GitHub의 동시성 제어로 병렬 실행 제한

조직 전체 사용량 추적은 애널리틱스 대시보드와 모니터링을, 사용량 측정과 청구는 비용을 참고하세요.

클라우드 제공자 사용 (Use a cloud provider)

기본적으로 Claude Code GitHub Action은 API 키나 OAuth 토큰으로 Claude API를 직접 호출합니다. 대신 자기 클라우드 계정으로 추론을 라우팅하려면 제공자 입력을 설정하고 클라우드 제공자와 함께 Claude Code GitHub Actions 사용을 따르세요.

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

세 제공자 모두 OIDC 아이덴티티 페더레이션으로 인증하므로 Claude API 키 대신 인증하면 리포지토리에 정적 클라우드 자격 증명을 저장하지 않습니다.

문제 해결 (Troubleshooting)

Claude가 @claude 명령에 응답하지 않음 (Claude not responding to @claude commands)

• GitHub App이 리포지토리에 설치됐는지 확인
• 리포지토리에 워크플로우가 활성화됐는지 확인
• API 키나 OAuth 토큰이 리포지토리 시크릿에 설정됐는지 확인
• 댓글에 @claude가 완전한 단어로 들어 있지 /claude나 @claude-bot이 아닌지 확인
• 댓글 작성 사용자가 리포지토리에 쓰기 접근이 있는지 확인. 예외는 실행을 트리거할 수 있는 사람 참고

Claude 커밋에서 CI가 실행되지 않음 (CI not running on Claude's commits)

• GitHub는 기본 GITHUB_TOKEN으로 만든 커밋에는 워크플로우를 트리거하지 않습니다. Claude Code GitHub Action에 github_token: ${{ secrets.GITHUB_TOKEN }}을 넘긴다면 제거해 Claude GitHub App으로 인증하게 하거나, 커스텀 앱 토큰을 대신 넘기세요.
• CI 워크플로우의 트리거에 Claude가 푸시하는 이벤트(push, pull_request 등)가 포함되는지 확인

인증 오류 (Authentication errors)

• 워크플로우를 디버깅하기 전에 로컬에서 claude로 API 키나 OAuth 토큰이 유효한지 테스트
• Bedrock, Agent Platform, Foundry는 클라우드 제공자 페이지의 문제 해결 섹션 참고

더 많은 해결책은 Claude Code GitHub Action의 FAQ를 참고하세요.

고급 구성 (Advanced configuration)

Action 파라미터 (Action parameters)

가장 흔히 쓰는 입력입니다. 각각 anthropics/claude-code-action 단계의 with: 키에 대응합니다.

파라미터	설명	필수
prompt	Claude에 대한 지시. 평문 또는 스킬 호출. 생략하면 Claude가 트리거 문구에 응답함	아니요
claude_args	Claude Code에 전달하는 CLI 인자	아니요
anthropic_api_key	Claude API 키	Claude API의 경우, claude_code_oauth_token이나 워크로드 아이덴티티 페더레이션을 쓰지 않으면 필요. Bedrock, Agent Platform, Foundry에선 사용 안 함
claude_code_oauth_token	claude setup-token으로 생성한, Claude 구독 인증용 OAuth 토큰	아니요
github_token	GitHub 작업용 토큰. 생략하면 Claude Code GitHub Action이 Claude GitHub App으로 인증	아니요
plugin_marketplaces	줄바꿈으로 구분된 플러그인 마켓플레이스 Git URL 목록	아니요
plugins	실행 전 설치할 줄바꿈 구분 플러그인 이름 목록	아니요
settings	JSON 문자열 또는 settings JSON 파일 경로 형태의 Claude Code 설정	아니요
trigger_phrase	Claude가 응답하는 트리거 문구. 기본: @claude	아니요
use_bedrock	Claude API 대신 Amazon Bedrock 사용	아니요
use_vertex	Claude API 대신 Google Cloud's Agent Platform 사용	아니요
use_foundry	Claude API 대신 Microsoft Foundry 사용	아니요

전체 입력 목록은 Claude Code GitHub Action의 구성 레퍼런스를 참고하세요.

CLI 인자 전달 (Pass CLI arguments)

claude_args 파라미터는 아무 Claude Code 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: 디버그 출력 활성화

베타에서 업그레이드 (Upgrade from beta)

워크플로우가 여전히 anthropics/claude-code-action@beta를 참조한다면 v1로 업데이트하세요.

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가 됩니다.

전체 입력 매핑과 before/after 예시는 마이그레이션 가이드를 참고하세요.

더 알아보기

• 클라우드 제공자와 함께 Claude Code GitHub Actions 사용: Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry로 추론 라우팅
• 구성 레퍼런스: Action 입력 전체 목록
• Examples 디렉토리: 더 많은 시나리오용 바로 쓸 수 있는 워크플로우
• Code Review: 워크플로우 파일 유지 없이 자동 풀 리퀘스트 리뷰