Claude Code Action@v1

TMT

기능 및 한계

https://github.com/anthropics/claude-code-action/blob/main/docs/capabilities-and-limitations.md

Claude가 할 수 있는 것

단일 댓글로 응답: Claude는 진행 상황과 결과를 단일 초기 댓글을 업데이트하는 방식으로 동작합니다.
질문에 답변: 코드를 분석하고 설명을 제공합니다.
코드 변경 구현: 요청에 따라 간단하거나 중간 수준의 코드 변경을 수행합니다.
풀 리퀘스트 준비: 브랜치에 커밋을 생성하고 미리 작성된 PR 생성 페이지로 연결합니다.
코드 리뷰 수행: PR 변경 사항을 분석하고 상세한 피드백을 제공합니다.
스마트 브랜치 처리:
- 이슈에서 트리거될 때: 항상 작업을 위한 새 브랜치를 생성합니다.
- 오픈 PR에서 트리거될 때: 항상 기존 PR 브랜치에 직접 푸시합니다.
- 닫힌 PR에서 트리거될 때: 원래 브랜치가 더 이상 활성 상태가 아니므로 새 브랜치를 생성합니다.
GitHub Actions 결과 보기: ‎⁠actions: read⁠ 권한이 구성된 경우, 태그된 PR에서 워크플로 실행, 작업 로그, 테스트 결과에 접근할 수 있습니다(자세한 내용은 CI/CD 통합을 위한 추가 권한.

Claude가 할 수 없는 것

PR 리뷰 제출: Claude는 공식 GitHub PR 리뷰를 제출할 수 없습니다.
PR 승인: 보안상의 이유로 Claude는 풀 리퀘스트를 승인할 수 없습니다.
여러 댓글 게시: Claude는 오직 초기 댓글을 업데이트하는 방식으로만 동작합니다.
컨텍스트 외부 명령 실행: Claude는 리포지토리 및 PR/이슈 컨텍스트에만 접근할 수 있습니다.
임의의 Bash 명령 실행: 기본적으로, ‎⁠allowed_tools⁠ 설정을 통해 명시적으로 허용되지 않는 한 Bash 명령을 실행할 수 없습니다.
브랜치 작업 수행: 브랜치 병합, 리베이스, 기타 git 작업(커밋 푸시 외)은 할 수 없습니다.

작동 방식

트리거 감지: 트리거 문구(기본값: ‎⁠@claude⁠)가 포함된 댓글이나 특정 사용자에게 이슈가 할당되는 것을 감지합니다.
컨텍스트 수집: PR/이슈, 댓글, 코드 변경 사항을 분석합니다.
스마트 응답: 질문에 답하거나 변경 사항을 구현합니다.
브랜치 관리: 사람 작성자의 경우 새 PR을 생성하고, Claude 자신의 PR의 경우 직접 푸시합니다.
커뮤니케이션: 모든 단계에서 업데이트를 게시하여 진행 상황을 안내합니다.

이 액션은 ‎⁠anthropics/claude-code-base-action⁠ 위에 구축되었습니다.

클라우드 제공업체

https://github.com/anthropics/claude-code-action/blob/main/docs/cloud-providers.md

Claude에 인증하는 방법은 다음 세 가지입니다:

직접 Anthropic API (기본값)
OIDC 인증을 사용하는 Amazon Bedrock
OIDC 인증을 사용하는 Google Vertex AI

AWS Bedrock 및 Google Vertex AI의 자세한 설정 방법은 공식 문서를 참고하세요.

참고:

Bedrock과 Vertex는 오직 OIDC 인증만 사용합니다.
AWS Bedrock은 특정 모델에 대해 자동으로 크로스 리전 추론 프로필을 사용합니다.
크로스 리전 추론 프로필 모델의 경우, 해당 추론 프로필이 사용하는 모든 리전에서 Claude 모델에 대한 접근 권한을 요청하고 부여받아야 합니다.

고급 구성

https://github.com/anthropics/claude-code-action/blob/main/docs/configuration.md

사용자 지정 MCP 구성 사용

‎⁠mcp_config⁠ 입력을 사용하면 Claude의 기능을 확장하기 위해 사용자 지정 MCP(Model Context Protocol) 서버를 추가할 수 있습니다. 이러한 서버는 기본 제공 GitHub MCP 서버와 병합됩니다.

기본 예시: 순차적 사고 서버 추가

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "sequential-thinking": {
            "command": "npx",
            "args": [
              "-y",
              "@modelcontextprotocol/server-sequential-thinking"
            ]
          }
        }
      }
    allowed_tools: "mcp__sequential-thinking__sequentialthinking" # 중요: 서버의 각 MCP 도구를 여기에 쉼표로 구분하여 반드시 나열해야 합니다
    # ... 기타 입력값

MCP 서버에 Secret 전달하기

API 키나 토큰과 같은 민감한 정보가 필요한 MCP 서버의 경우, GitHub Secrets를 환경 변수로 사용하세요:

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "custom-api-server": {
            "command": "npx",
            "args": ["-y", "@example/api-server"],
            "env": {
              "API_KEY": "${{ secrets.CUSTOM_API_KEY }}",
              "BASE_URL": "https://api.example.com"
            }
          }
        }
      }
    # ... 기타 입력값

uv로 Python MCP 서버 사용하기

‎⁠uv⁠로 관리되는 Python 기반 MCP 서버의 경우, 서버가 있는 디렉터리를 지정해야 합니다:

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "my-python-server": {
            "type": "stdio",
            "command": "uv",
            "args": [
              "--directory",
              "${{ github.workspace }}/path/to/server/",
              "run",
              "server_file.py"
            ]
          }
        }
      }
    allowed_tools: "my-python-server__<tool_name>" # <tool_name>을 서버의 도구 이름으로 교체하세요
    # ... 기타 입력값

예를 들어, Python MCP 서버가 ‎⁠mcp_servers/weather.py⁠에 있다면 다음과 같이 사용합니다:

"args":
  ["--directory", "${{ github.workspace }}/mcp_servers/", "run", "weather.py"]

중요:

API 키, 토큰, 비밀번호 등과 같은 민감한 값은 항상 GitHub Secrets(‎⁠${{ secrets.SECRET_NAME }}⁠)를 사용하세요. 워크플로 파일에 직접 하드코딩하지 마세요.
사용자 지정 서버는 동일한 이름의 기본 제공 서버를 덮어씁니다.

CI/CD 통합을 위한 추가 권한

‎⁠additional_permissions⁠ 입력을 사용하면 필요한 권한을 부여할 때 Claude가 GitHub Actions 워크플로 정보를 액세스할 수 있습니다. 이는 CI/CD 실패 분석 및 워크플로 문제 디버깅에 특히 유용합니다.

GitHub Actions 액세스 활성화

Claude가 워크플로 실행 결과, 작업 로그, CI 상태를 볼 수 있도록 하려면:

GitHub 토큰에 필요한 권한을 부여하세요:

기본 ‎⁠GITHUB_TOKEN⁠을 사용할 때, 워크플로에 ‎⁠actions: read⁠ 권한을 추가하세요:

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read # 이 줄을 추가하세요

추가 권한으로 액션을 구성하세요:

- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    additional_permissions: |
      actions: read
    # ... 기타 입력값

Claude가 CI/CD 도구에 자동으로 액세스합니다: ‎⁠actions: read⁠를 활성화하면 Claude는 다음 MCP 도구를 사용할 수 있습니다:

‎⁠mcp__github_ci__get_ci_status⁠ - 워크플로 실행 상태 보기
‎⁠mcp__github_ci__get_workflow_run_details⁠ - 상세 워크플로 정보 가져오기
mcp__github_ci__download_job_log⁠ - 작업 로그 다운로드 및 분석

예시: 실패한 CI 실행 디버깅

name: Claude CI Helper
on:
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read # CI 액세스에 필요

jobs:
  claude-ci-helper:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          additional_permissions: |
            actions: read
          # 이제 Claude가 "@claude why did the CI fail?"에 응답할 수 있습니다

중요 사항:

워크플로에서 GitHub 토큰에 반드시 ‎⁠actions: read⁠ 권한이 있어야 합니다
권한이 없으면 Claude가 경고하고 추가를 제안합니다
현재는 ‎⁠actions: read⁠만 지원되지만, 형식상 향후 확장이 가능합니다

사용자 지정 환경 변수

‎⁠settings⁠ 입력을 사용하여 Claude Code 실행에 사용자 지정 환경 변수를 전달할 수 있습니다. 이는 특정 환경 변수가 필요한 CI/테스트 설정에 유용합니다:

- uses: anthropics/claude-code-action@v1
  with:
    settings: |
      {
        "env": {
          "NODE_ENV": "test",
          "CI": "true",
          "DATABASE_URL": "postgres://test:test@localhost:5432/test_db"
        }
      }
    # ... 기타 입력값

이 환경 변수들은 Claude Code 실행 중에 사용 가능하며, 테스트, 빌드 프로세스 또는 특정 환경 구성이 필요한 명령을 실행할 수 있습니다.

대화 턴 제한

‎⁠claude_args⁠ 입력을 사용하여 Claude가 작업 실행 중에 주고받을 수 있는 대화 횟수를 제한할 수 있습니다. 이는 다음에 유용합니다:

과도한 대화로 인한 비용 통제
자동화된 워크플로의 시간 제한 설정
CI/CD 파이프라인에서 예측 가능한 동작 보장

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --max-turns 5  # 대화 턴을 5회로 제한
    # ... 기타 입력값

턴 제한에 도달하면 Claude는 실행을 정상적으로 중단합니다. 일반적인 작업을 완료할 수 있는 충분한 턴 수를 선택하되, 과도한 사용을 방지하세요.

사용자 지정 도구

기본적으로 Claude가 접근할 수 있는 기능은 다음과 같습니다:

파일 작업(읽기, 커밋, 파일 편집, 읽기 전용 git 명령)
댓글 관리(댓글 생성/업데이트)
기본 GitHub 작업

Claude는 기본적으로 임의의 Bash 명령을 실행할 수 없습니다. 특정 명령(npm install, npm test 등)을 실행하려면 ‎⁠claude_args⁠ 구성에서 명시적으로 허용해야 합니다:

참고: 리포지토리 루트에 ‎⁠.mcp.json⁠ 파일이 있으면 Claude가 정의된 MCP 서버 도구를 자동으로 감지하고 사용합니다. 그러나 이러한 도구도 반드시 명시적으로 허용해야 합니다.

- uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --allowedTools "Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell"
      --disallowedTools "TaskOutput,KillTask"
    # ... 기타 입력값

참고: 기본 GitHub 도구는 항상 포함됩니다. 추가 도구(Bash 명령 등)를 추가하려면 ‎⁠--allowedTools⁠를 사용하고, 특정 도구를 사용하지 않으려면 ‎⁠--disallowedTools⁠를 사용하세요.

사용자 지정 모델

‎⁠claude_args⁠를 사용하여 Claude 모델을 지정할 수 있습니다:

- uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --model claude-4-0-sonnet-20250805
    # ... 기타 입력값

공급자별 모델 지정 예시:

# AWS Bedrock
- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: |
      --model anthropic.claude-4-0-sonnet-20250805-v1:0
    # ... 기타 입력값

# Google Vertex AI
- uses: anthropics/claude-code-action@v1
  with:
    use_vertex: "true"
    claude_args: |
      --model claude-4-0-sonnet@20250805
    # ... 기타 입력값

Claude Code 설정

모델 선택, 환경 변수, 권한, 후크 등과 같은 동작을 사용자 지정하기 위해 Claude Code 설정을 제공할 수 있습니다. 설정은 JSON 문자열 또는 설정 파일 경로로 제공할 수 있습니다.

옵션 1: 설정 파일

- uses: anthropics/claude-code-action@v1
  with:
    settings: "path/to/settings.json"
    # ... 기타 입력값

옵션 2: 인라인 설정

- uses: anthropics/claude-code-action@v1
  with:
    settings: |
      {
        "model": "claude-opus-4-1-20250805",
        "env": {
          "DEBUG": "true",
          "API_URL": "https://api.example.com"
        },
        "permissions": {
          "allow": ["Bash", "Read"],
          "deny": ["WebFetch"]
        },
        "hooks": {
          "PreToolUse": [{
            "matcher": "Bash",
            "hooks": [{
              "type": "command",
              "command": "echo Running bash command..."
            }]
          }]
        }
      }
    # ... 기타 입력값

설정은 다음을 포함한 모든 Claude Code 설정 옵션을 지원합니다:

‎⁠model⁠: 기본 모델 재정의
‎⁠env⁠: 세션용 환경 변수
‎⁠permissions⁠: 도구 사용 권한
‎⁠hooks⁠: 도구 실행 전/후 후크
기타…

자세한 설정 옵션과 설명은 Claude Code settings documentation에서 확인하세요.

참고:

MCP 서버가 정상적으로 작동하도록 이 액션에서 ‎⁠enableAllProjectMcpServers⁠ 설정은 항상 ‎⁠true⁠로 설정됩니다.
‎⁠claude_args⁠ 입력은 Claude Code CLI 인수에 직접 접근하며, 설정보다 우선 적용됩니다.
간단한 구성에는 ‎⁠claude_args⁠를, 후크와 환경 변수 등 복잡한 구성에는 ‎⁠settings⁠를 사용하는 것을 권장합니다.

사용 중단된 입력값에서 마이그레이션

많은 개별 입력 파라미터가 ‎⁠claude_args⁠ 또는 ‎⁠settings⁠로 통합되었습니다. 마이그레이션 방법은 다음과 같습니다:

기존 입력값	새로운 방식
`allowed_tools`	`claude_args: "--allowedTools Tool1,Tool2"` 사용
`disallowed_tools`	`claude_args: "--disallowedTools Tool1,Tool2"` 사용
`max_turns`	`claude_args: "--max-turns 10"` 사용
`model`	`claude_args: "--model claude-4-0-sonnet-20250805"` 사용
`claude_env`	`"env"` 객체와 함께 `settings` 사용
`custom_instructions`	`claude_args: "--system-prompt 'Your instructions'"` 사용
`direct_prompt`	대신 `prompt` 입력값 사용
`override_prompt`	GitHub 컨텍스트 변수와 함께 `prompt` 사용

커스텀 자동화

https://github.com/anthropics/claude-code-action/blob/main/docs/custom-automations.md

이 예시들은 Claude가 GitHub 이벤트에 따라 자동으로 동작하도록 설정하는 방법을 보여줍니다. ‎⁠prompt⁠ 입력을 제공하면, 액션이 에이전트 모드로 자동 실행되어 수동 @멘션이 필요하지 않습니다. ‎⁠prompt⁠ 없이 실행하면, 인터랙티브 모드로 동작하여 @claude 멘션에 응답합니다.

지원되는 GitHub 이벤트

이 액션은 다음 GitHub 이벤트를 지원합니다(GitHub 이벤트 트리거에 대해 더 알아보기):

pull_request⁠ - PR이 열리거나 동기화될 때
‎⁠issue_comment⁠ - 이슈 또는 PR에 댓글이 생성될 때
‎⁠pull_request_comment⁠ - PR diff에 댓글이 달릴 때
‎⁠issues⁠ - 이슈가 열리거나 할당될 때
‎⁠pull_request_review⁠ - PR 리뷰가 제출될 때
‎⁠pull_request_review_comment⁠ - PR 리뷰에 댓글이 달릴 때
‎⁠repository_dispatch⁠ - API를 통해 트리거되는 커스텀 이벤트(곧 지원 예정)
‎⁠workflow_dispatch⁠ - 수동 워크플로우 트리거(곧 지원 예정)

자동 문서 업데이트

특정 파일이 변경될 때 문서를 자동으로 업데이트합니다(‎⁠examples/claude-pr-path-specific.yml):

on:
  pull_request:
    paths:
      - "src/api/**/*.ts"

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      prompt: |
        Update the API documentation in README.md to reflect
        the changes made to the API endpoints in this PR.
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

API 파일이 수정되면, 액션은 ‎⁠prompt⁠가 제공된 것을 자동으로 감지하고 에이전트 모드로 실행됩니다. Claude는 README를 최신 엔드포인트 문서로 업데이트하고 변경 사항을 PR에 다시 푸시하여 코드와 문서가 항상 동기화되도록 유지합니다.

작성자별 코드 리뷰

특정 작성자 또는 외부 기여자의 PR을 자동으로 리뷰합니다(‎⁠examples/claude-review-from-author.yml):

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review-by-author:
    if: |
      github.event.pull_request.user.login == 'developer1' ||
      github.event.pull_request.user.login == 'external-contributor'
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Please provide a thorough review of this pull request.
            Pay extra attention to coding standards, security practices,
            and test coverage since this is from an external contributor.
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

신규 팀원, 외부 기여자, 추가 안내가 필요한 특정 개발자의 PR을 자동으로 리뷰하는 데 적합합니다. ‎⁠prompt⁠가 제공되면 액션이 자동으로 에이전트 모드로 실행됩니다.

커스텀 프롬프트 템플릿

GitHub 컨텍스트 변수를 활용하여 ‎⁠prompt⁠ 입력에 동적 자동화를 적용할 수 있습니다:

- uses: anthropics/claude-code-action@v1
  with:
    prompt: |
      Analyze PR #${{ github.event.pull_request.number }} in ${{ github.repository }} for security vulnerabilities.

      Focus on:
      - SQL injection risks
      - XSS vulnerabilities
      - Authentication bypasses
      - Exposed secrets or credentials

      Provide severity ratings (Critical/High/Medium/Low) for any issues found.      
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

표준 GitHub Actions 문법을 사용하여 모든 GitHub 컨텍스트 변수를 사용할 수 있습니다:

${{ github.repository }} - 저장소 이름
${{ github.event.pull_request.number }} - PR 번호
${{ github.event.issue.number }} - 이슈 번호
${{ github.event.pull_request.title }} - PR 제목
${{ github.event.pull_request.body }} - PR 설명
${{ github.event.comment.body }} - 댓글 내용
${{ github.actor }} - 워크플로우를 트리거한 사용자
${{ github.base_ref }} - PR의 기준 브랜치
${{ github.head_ref }} - PR의 헤드 브랜치

claude_args를 활용한 고급 설정

Claude의 동작을 더 세밀하게 제어하려면, ‎⁠claude_args⁠ 입력을 사용해 CLI 인자를 직접 전달할 수 있습니다:

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "이 PR의 성능 문제를 리뷰하세요"
    claude_args: |
      --max-turns 15
      --model claude-4-0-sonnet-20250805
      --allowedTools Edit,Read,Write,Bash
      --system-prompt "You are a performance optimization expert. Focus on identifying bottlenecks and suggesting improvements."
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

이렇게 하면 간단한 액션 인터페이스를 유지하면서 Claude Code CLI의 모든 기능을 활용할 수 있습니다.

실험적 기능

https://github.com/anthropics/claude-code-action/blob/main/docs/experimental.md

참고: 실험적 기능은 불안정하며 프로덕션 환경에서 지원되지 않습니다. 언제든지 변경되거나 제거될 수 있습니다.

자동 모드 감지

이 액션은 워크플로우 컨텍스트에 따라 적절한 실행 모드를 자동으로 감지하여, 수동으로 모드를 설정할 필요가 없습니다.

인터랙티브 모드(태그 모드)

Claude가 @멘션, 이슈 할당, 또는 라벨을 감지할 때 활성화되며, 명시적인 ‎⁠prompt⁠가 없는 경우에 작동합니다.

트리거: 댓글에서 ‎⁠@claude⁠ 멘션, claude 사용자에게 이슈 할당, 라벨 적용
기능: 진행 상황 체크박스가 있는 추적 댓글 생성, 전체 구현 기능 제공
사용 사례: 인터랙티브 코드 지원, Q&A, 구현 요청

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    # No prompt needed - responds to @claude mentions

자동화 모드(에이전트 모드)

‎⁠prompt⁠ 입력이 제공될 때 자동으로 활성화됩니다.

트리거: ‎⁠prompt⁠ 입력이 제공되는 모든 GitHub 이벤트
기능: @claude 멘션 없이 직접 실행, 자동화에 최적화
사용 사례: 자동화된 PR 리뷰, 예약된 작업, 워크플로우 자동화

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: |
      Check for outdated dependencies and create an issue if any are found.
    # Automatically runs in agent mode when prompt is provided

작동 방식

액션은 다음 논리를 사용하여 모드를 결정합니다:

‎⁠**prompt⁠가 제공된 경우** → 에이전트 모드로 자동화 실행
‎⁠prompt⁠가 없고 @claude가 멘션된 경우 → 태그 모드로 인터랙션 실행
둘 다 아닌 경우 → 아무 작업도 하지 않음

이 자동 감지 기능으로 워크플로우가 더 간단하고 직관적으로 되어, 다양한 모드를 이해하거나 설정할 필요가 없습니다.

고급 모드 제어

특수한 사용 사례를 위해 ‎⁠claude_args⁠를 사용하여 동작을 세밀하게 조정할 수 있습니다:

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR"
    claude_args: |
      --max-turns 20
      --system-prompt "You are a code review specialist"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

사용법

https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md

저장소에 워크플로 파일(예: ‎.github/workflows/claude.yml)을 추가하세요:

name: Claude Assistant
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned, labeled]
  pull_request_review:
    types: [submitted]

jobs:
  claude-response:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # 또는 OAuth 토큰 사용:
          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

          # 선택 사항: 자동화 워크플로를 위한 프롬프트 제공
          # prompt: "Review this PR for security issues"

          # 선택 사항: Claude CLI에 고급 인수 전달
          # claude_args: |
          #   --max-turns 10
          #   --model claude-4-0-sonnet-20250805

          # 선택 사항: 사용자 지정 트리거 문구 추가(기본값: @claude)
          # trigger_phrase: "/claude"
          # 선택 사항: 이슈에 대한 담당자 트리거 추가
          # assignee_trigger: "claude"
          # 선택 사항: 이슈에 대한 라벨 트리거 추가
          # label_trigger: "claude"
          # 선택 사항: 추가 권한 부여(해당 GitHub 토큰 권한 필요)
          # additional_permissions: |
          #   actions: read
          # 선택 사항: 봇 사용자가 액션을 트리거할 수 있도록 허용
          # allowed_bots: "dependabot[bot],renovate[bot]"

Inputs

입력값	설명	필수	기본값
`anthropic_api_key`	Anthropic API 키(직접 API 사용 시 필수, Bedrock/Vertex 사용 시 불필요)	아니오*	-
`claude_code_oauth_token`	Claude Code OAuth 토큰(anthropic_api_key의 대안)	아니오*	-
`prompt`	Claude에게 전달할 지침. 자동화 워크플로를 위한 직접 프롬프트 또는 사용자 지정 템플릿 가능	아니오	-
`claude_args`	Claude CLI에 직접 전달할 추가 인수(예: `--max-turns 10 --model claude-4-0-sonnet-20250805`)	아니오	“”
`base_branch`	새 브랜치 생성 시 사용할 기준 브랜치(예: ‘main’, ‘develop’)	아니오	-
`use_sticky_comment`	PR 코멘트 전달 시 하나의 코멘트만 사용(풀 리퀘스트 이벤트 워크플로에만 적용)	아니오	`false`
`github_token`	Claude가 작업할 수 있도록 하는 GitHub 토큰. 직접 만든 GitHub 앱을 연결할 때만 포함하세요!	아니오	-
`use_bedrock`	직접 Anthropic API 대신 OIDC 인증을 통한 Amazon Bedrock 사용	아니오	`false`
`use_vertex`	직접 Anthropic API 대신 OIDC 인증을 통한 Google Vertex AI 사용	아니오	`false`
`mcp_config`	내장 GitHub MCP 서버와 병합되는 추가 MCP 구성(JSON 문자열)	아니오	“”
`assignee_trigger`	액션을 트리거하는 담당자 사용자명(예: @claude). 이슈 할당에만 사용	아니오	-
`label_trigger`	이슈에 라벨이 적용될 때 액션을 트리거하는 라벨명(예: “claude”)	아니오	-
`trigger_phrase`	코멘트, 이슈/PR 본문, 이슈 제목에서 감지할 트리거 문구	아니오	`@claude`
`branch_prefix`	Claude 브랜치에 사용할 접두사(기본값: ‘claude/’, 대시 형식은 ‘claude-’)	아니오	`claude/`
`settings`	Claude Code 설정(JSON 문자열 또는 설정 JSON 파일 경로)	아니오	“”
`additional_permissions`	활성화할 추가 권한. 현재 ‘actions: read’만 지원(워크플로 결과 보기용)	아니오	“”
`experimental_allowed_domains`	네트워크 접근을 이 도메인으로만 제한(줄바꿈으로 구분)	아니오	“”
`use_commit_signing`	GitHub의 커밋 서명 검증을 통한 커밋 서명 활성화. false일 경우 Claude는 표준 git 명령 사용	아니오	`false`
`allowed_bots`	허용할 봇 사용자명 목록(쉼표로 구분), ’*’는 모든 봇 허용. 빈 문자열(기본값)은 봇 허용 안 함	아니오	“”

자주 묻는 질문(FAQ)

https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md

이 FAQ는 Claude Code GitHub Action을 사용할 때 자주 묻는 질문과 주의할 점을 다룹니다.

트리거 및 인증

자동화된 워크플로에서 @claude 태그를 사용해도 작동하지 않는 이유는 무엇인가요?

‎⁠github-actions⁠ 사용자는 이후의 GitHub Actions 워크플로를 트리거할 수 없습니다. 이는 무한 루프를 방지하기 위한 GitHub의 보안 기능입니다. 이를 해결하려면, 일반 사용자처럼 동작하는 개인 액세스 토큰(PAT)이나 별도의 앱 토큰을 사용해야 합니다. 워크플로에서 이슈나 PR에 댓글을 남길 때는 워크플로에서 생성된 ‎⁠GITHUB_TOKEN⁠ 대신 PAT을 사용하세요.

Claude가 트리거 권한이 없다고 하는 이유는 무엇인가요?

저장소에 쓰기 권한이 있는 사용자만 Claude를 트리거할 수 있습니다. 이는 무단 사용을 방지하기 위한 보안 기능입니다. 댓글을 남기는 사용자가 저장소에 최소한 쓰기 권한이 있는지 확인하세요.

내 저장소의 이슈에 @claude를 할당할 수 없는 이유는 무엇인가요?

공개 저장소에서는 Claude를 자유롭게 할당할 수 있습니다. 하지만 비공개 조직 저장소에서는 조직 내 사용자만 할당할 수 있으며, Claude는 조직 외부 사용자입니다. 이 경우에는 별도의 사용자 계정을 만들어야 합니다.

OIDC 인증 오류가 발생하는 이유는 무엇인가요?

기본 GitHub App 인증을 사용하는 경우, 워크플로에 ‎⁠id-token: write⁠ 권한을 추가해야 합니다:

permissions:
  contents: read
  id-token: write # OIDC 인증에 필요

OIDC 토큰은 Claude GitHub 앱이 동작하는 데 필요합니다. GitHub 앱을 사용하지 않으려면, 대신 Claude가 동작할 수 있도록 ‎⁠github_token⁠ 입력값을 제공할 수 있습니다. 자세한 내용은 Claude Code 권한 문서를 참고하세요.

Claude의 기능 및 제한

Claude에게 워크플로 파일을 업데이트하라고 해도 반영되지 않는 이유는 무엇인가요?

Claude의 GitHub App은 보안상의 이유로 워크플로 쓰기 권한이 없습니다. 이는 CI/CD 설정을 변경해 의도치 않은 결과가 발생하는 것을 방지하기 위한 조치입니다. 향후에는 이 부분을 재고할 수 있습니다.

Claude가 브랜치를 리베이스하지 않는 이유는 무엇인가요?

기본적으로 Claude는 브랜치에 파괴적이지 않은 변경만 커밋 도구를 사용해 적용합니다. Claude는 다음과 같이 동작합니다:

호출된 브랜치(자신의 브랜치 또는 PR 브랜치) 외의 브랜치에는 절대 푸시하지 않음
강제 푸시나 파괴적 작업은 절대 수행하지 않음

필요하다면 ‎⁠claude_args⁠ 입력값을 통해 추가 도구를 허용할 수 있습니다:

claude_args: |
  --allowedTools "Bash(git rebase:*)"  # 주의해서 사용하세요

Claude가 풀 리퀘스트(PR)를 생성하지 않는 이유는 무엇인가요?

Claude는 기본적으로 PR을 생성하지 않습니다. 대신 브랜치에 커밋을 푸시하고, 미리 작성된 PR 제출 페이지 링크를 제공합니다. 이 방식은 저장소의 브랜치 보호 규칙을 준수하며, PR 생성에 대한 최종 제어권을 사용자에게 제공합니다.

Claude가 내 GitHub Actions CI 결과를 볼 수 있나요?

네! Claude는 PR에서 GitHub Actions 워크플로 실행, 작업 로그, 테스트 결과에 접근할 수 있습니다. 이를 활성화하려면:

워크플로에 ‎⁠actions: read⁠ 권한을 추가하세요:

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read

액션에 추가 권한을 설정하세요:

- uses: anthropics/claude-code-action@v1
  with:
    additional_permissions: |
      actions: read

이렇게 하면 Claude가 CI 실패를 분석하고 워크플로 문제를 디버깅하는 데 도움을 줄 수 있습니다. 커밋 전에 로컬에서 테스트를 실행하려면 요청 시 Claude에게 지시할 수 있습니다.

Claude가 새 댓글을 생성하지 않고 하나의 댓글만 업데이트하는 이유는 무엇인가요?

Claude는 PR/이슈 토론이 복잡해지는 것을 방지하기 위해 하나의 댓글만 업데이트하도록 설정되어 있습니다. 진행 상황과 최종 결과를 포함한 모든 Claude의 응답은 같은 댓글에 체크박스 형태로 표시됩니다.

브랜치 및 커밋 동작

닫힌 PR에 댓글을 달았더니 Claude가 새 브랜치를 만든 이유는 무엇인가요?

Claude의 브랜치 동작은 상황에 따라 다릅니다:

열린 PR: 기존 PR 브랜치에 직접 푸시
닫힌/병합된 PR: 새 브랜치 생성(닫힌 PR 브랜치에는 푸시할 수 없음)
이슈: 항상 타임스탬프가 포함된 새 브랜치 생성

커밋이 얕거나 히스토리가 누락된 이유는 무엇인가요?

성능을 위해 Claude는 얕은 클론을 사용합니다:

PR: ‎⁠--depth=20⁠(최근 20개 커밋)
새 브랜치: ‎⁠--depth=1⁠(단일 커밋)

전체 히스토리가 필요하다면, Claude를 호출하기 전에 워크플로의 ‎⁠actions/checkout⁠ 단계에서 설정할 수 있습니다.

- uses: actions/checkout@v4
  depth: 0 # 전체 저장소 히스토리 가져오기

설정 및 도구

자동 모드 감지는 어떻게 동작하나요?

액션은 자동으로 인터랙티브 모드와 자동화 모드를 감지합니다:

prompt⁠ 입력값이 있으면: 자동화 모드 - @claude 언급을 기다리지 않고 즉시 실행
‎⁠prompt⁠ 입력값이 없으면: 인터랙티브 모드 - 댓글에서 @claude 언급을 기다림

이 자동 감지 기능으로 모드를 수동으로 설정할 필요가 없습니다.

예시:

# 자동화 모드 - 자동 실행
prompt: "Review this PR for security vulnerabilities"
# 인터랙티브 모드 - @claude 언급을 기다림
# (prompt 미제공)

‎⁠#### direct_prompt⁠와 ‎⁠custom_instructions⁠는 어떻게 되었나요?

이 입력값들은 v1.0에서 더 이상 사용되지 않습니다:

‎⁠direct_prompt⁠ → 대신 ‎⁠prompt⁠ 사용
‎⁠custom_instructions⁠ → 대신 ‎⁠claude_args⁠의 ‎⁠--system-prompt⁠ 사용

마이그레이션 예시:

# 이전(v0.x)
direct_prompt: "Review this PR"
custom_instructions: "Focus on security"

# 새로운(v1.0)
prompt: "Review this PR"
claude_args: |
  --system-prompt "Focus on security"

Claude가 내 bash 명령을 실행하지 않는 이유는 무엇인가요?

Bash 도구는 기본적으로 비활성화되어 있습니다. ‎⁠claude_args⁠를 사용해 개별 bash 명령을 활성화할 수 있습니다:

claude_args: |
  --allowedTools "Bash(npm:*),Bash(git:*)"  # npm과 git 명령만 허용

Claude가 여러 저장소에서 동작할 수 있나요?

아니요, Claude의 GitHub 앱 토큰은 현재 저장소에만 샌드박스 처리됩니다. 다른 저장소에는 푸시할 수 없습니다. 다만, 공개 저장소는 읽을 수 있지만, 이를 위해서는 도구를 설정해야 합니다.

댓글이 claude[bot]으로 게시되지 않는 이유는 무엇인가요?

액션이 내장 인증을 사용할 때 댓글이 claude[bot]으로 표시됩니다. 하지만 워크플로에 ‎⁠github_token⁠을 제공하면 해당 토큰의 사용자명으로 댓글이 게시됩니다.

해결 방법: 커스텀 GitHub App을 사용하지 않는 한 워크플로 파일에서 ‎⁠github_token⁠을 제거하세요.

참고: ‎⁠use_sticky_comment⁠ 기능은 claude[bot] 인증에서만 동작합니다. 커스텀 ‎⁠github_token⁠을 사용하면 sticky 댓글이 제대로 업데이트되지 않습니다. sticky 댓글은 claude[bot] 사용자명을 기대하기 때문입니다.

MCP 서버 및 확장 기능

기본적으로 제공되는 MCP 서버는 무엇인가요?

Claude Code Action은 두 개의 MCP 서버를 자동으로 구성합니다:

GitHub MCP 서버: GitHub API 작업용
파일 작업 서버: 고급 파일 조작용

하지만 이 서버의 도구도 ‎⁠claude_args⁠의 ‎⁠--allowedTools⁠로 명시적으로 허용해야 사용할 수 있습니다.

문제 해결

Claude가 무엇을 하는지 디버깅하려면 어떻게 해야 하나요?

Claude 실행의 전체 실행 추적을 보려면 GitHub Action 로그를 확인하세요.

`‎⁠@claude-mention⁠`이나 `‎⁠claude!`⁠로 Claude를 트리거할 수 없는 이유는 무엇인가요?

트리거는 단어 경계를 사용하므로 ‎⁠@claude⁠가 완전한 단어여야 합니다. ‎⁠@claude-bot⁠, ‎⁠@claude!⁠, ‎⁠claude@mention⁠과 같은 변형은 ‎⁠trigger_phrase⁠를 커스터마이즈하지 않는 한 동작하지 않습니다.

모범 사례

워크플로 파일에 권한을 항상 명시적으로 지정하세요
API 키는 GitHub Secrets를 사용하세요 - 절대 하드코딩하지 마세요
도구 권한은 구체적으로 지정하세요 - 필요한 것만 ‎⁠claude_args⁠로 활성화
중요한 PR에 사용하기 전에 별도 브랜치에서 테스트하세요
Claude의 토큰 사용량을 모니터링해 API 제한에 걸리지 않도록 하세요
병합 전에 Claude의 변경 사항을 꼼꼼히 검토하세요

Claude Code Action@v1

기능 및 한계

Claude가 할 수 있는 것

Claude가 할 수 없는 것

작동 방식

클라우드 제공업체

고급 구성

사용자 지정 MCP 구성 사용

기본 예시: 순차적 사고 서버 추가

MCP 서버에 Secret 전달하기

uv로 Python MCP 서버 사용하기

CI/CD 통합을 위한 추가 권한

GitHub Actions 액세스 활성화

예시: 실패한 CI 실행 디버깅

사용자 지정 환경 변수

대화 턴 제한

사용자 지정 도구

사용자 지정 모델

Claude Code 설정

옵션 1: 설정 파일

사용 중단된 입력값에서 마이그레이션

커스텀 자동화

지원되는 GitHub 이벤트

자동 문서 업데이트

작성자별 코드 리뷰

커스텀 프롬프트 템플릿

claude_args를 활용한 고급 설정

실험적 기능

자동 모드 감지

인터랙티브 모드(태그 모드)

자동화 모드(에이전트 모드)

작동 방식

고급 모드 제어

사용법

Inputs

자주 묻는 질문(FAQ)

트리거 및 인증

자동화된 워크플로에서 @claude 태그를 사용해도 작동하지 않는 이유는 무엇인가요?

Claude가 트리거 권한이 없다고 하는 이유는 무엇인가요?

내 저장소의 이슈에 @claude를 할당할 수 없는 이유는 무엇인가요?

OIDC 인증 오류가 발생하는 이유는 무엇인가요?

Claude의 기능 및 제한

Claude에게 워크플로 파일을 업데이트하라고 해도 반영되지 않는 이유는 무엇인가요?

Claude가 브랜치를 리베이스하지 않는 이유는 무엇인가요?

Claude가 풀 리퀘스트(PR)를 생성하지 않는 이유는 무엇인가요?

Claude가 내 GitHub Actions CI 결과를 볼 수 있나요?

Claude가 새 댓글을 생성하지 않고 하나의 댓글만 업데이트하는 이유는 무엇인가요?

브랜치 및 커밋 동작

닫힌 PR에 댓글을 달았더니 Claude가 새 브랜치를 만든 이유는 무엇인가요?

커밋이 얕거나 히스토리가 누락된 이유는 무엇인가요?

설정 및 도구

자동 모드 감지는 어떻게 동작하나요?

Claude가 내 bash 명령을 실행하지 않는 이유는 무엇인가요?

Claude가 여러 저장소에서 동작할 수 있나요?

댓글이 claude[bot]으로 게시되지 않는 이유는 무엇인가요?

MCP 서버 및 확장 기능

기본적으로 제공되는 MCP 서버는 무엇인가요?

문제 해결

Claude가 무엇을 하는지 디버깅하려면 어떻게 해야 하나요?

‎⁠@claude-mention⁠이나 ‎⁠claude!⁠로 Claude를 트리거할 수 없는 이유는 무엇인가요?

모범 사례

On this Page

`‎⁠@claude-mention⁠`이나 `‎⁠claude!`⁠로 Claude를 트리거할 수 없는 이유는 무엇인가요?