> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code GitHub Actions 사용 튜토리얼

> Claude Code 集成指南 - Ace Data Cloud

Claude Code는 Anthropic이 출시한 **Agentic Coding** 도구로, 세계에서 가장 강력한 프로그래밍 에이전트 중 하나로 알려져 있습니다. Claude Code GitHub Actions는 AI 프로그래밍 기능을 GitHub 워크플로우에 통합할 수 있게 해주며, PR 또는 Issue에서 `@claude`를 입력하면 Claude가 자동으로 코드를 분석하고, PR을 생성하며, 기능을 구현하고, 버그를 수정합니다.

이 문서는 AceData Cloud의 프록시 서비스를 통해 Claude Code GitHub Actions를 구성하고 사용하는 방법을 주로 설명합니다.

## 신청 절차

Claude Code를 사용하려면 먼저 [Claude Messages 서비스 페이지](https://platform.acedata.cloud/documents/claude-messages)로 가서 "Acquire" 버튼을 클릭하여 요청에 필요한 자격 증명을 얻습니다:

![](https://cdn.acedata.cloud/nyq0xz.png)

로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 로그인 후에는 자동으로 현재 페이지로 돌아옵니다.

첫 신청 시 무료 한도가 제공되어 Claude Code 서비스를 무료로 체험할 수 있습니다.

## 기능 특징

* **즉시 PR 생성**: 요구 사항을 설명하면 Claude가 자동으로 완전한 Pull Request를 생성합니다.
* **자동 코드 구현**: Issue에서 `@claude`를 입력하면 Issue를 실행 가능한 코드로 변환합니다.
* **프로젝트 규칙 준수**: 자동으로 `CLAUDE.md`를 읽고, 코드 스타일과 프로젝트 규칙을 준수합니다.
* **안전하고 신뢰할 수 있음**: 코드는 GitHub의 Runner에서 실행되며, 데이터 안전이 보장됩니다.

## 구성 단계

### 단계 1: Claude GitHub App 설치

[https://github.com/apps/claude](https://github.com/apps/claude)로 가서 Claude GitHub App을 당신의 저장소에 설치합니다.

![GitHub Claude App 설치 페이지](https://cdn.acedata.cloud/ba4b8df66d.png)

이 App은 다음과 같은 저장소 권한이 필요합니다:

| 권한                | 수준           | 설명               |
| ----------------- | ------------ | ---------------- |
| **Contents**      | Read & Write | 저장소 파일 수정        |
| **Issues**        | Read & Write | Issue 응답         |
| **Pull requests** | Read & Write | PR 생성 및 변경 사항 푸시 |

### 단계 2: API 키 추가

AceData Cloud의 API 키를 저장소 Secret으로 추가합니다:

1. 저장소 **Settings** → **Secrets and variables** → **Actions**로 이동합니다.
2. **New repository secret**를 클릭합니다.
3. Name에 `ANTHROPIC_API_KEY`를 입력하고, Value에 AceData Cloud에서 얻은 API 토큰을 입력합니다.
4. **Add secret**를 클릭하여 저장합니다.

> **팁**: API 토큰은 [AceData Cloud 콘솔](https://platform.acedata.cloud/console)에서 확인할 수 있습니다.

### 단계 3: Workflow 파일 생성

저장소에 `.github/workflows/claude.yml` 파일을 생성합니다:

```yaml theme={null}
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request:
    types: [opened, synchronize]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

AceData Cloud의 프록시 API 엔드포인트를 사용해야 하는 경우, Workflow에 환경 변수를 설정해야 합니다:

```yaml theme={null}
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 }}
        env:
          ANTHROPIC_BASE_URL: "https://api.acedata.cloud"
```

## 사용 방법

### Issue 또는 PR 댓글에서 사용

구성이 완료되면, 어떤 Issue 또는 PR의 댓글에서 `@claude`를 입력하면 Claude가 자동으로 응답합니다:

```
@claude 이 Issue의 설명에 따라 기능을 구현해 주세요
@claude 이 PR의 코드 안전성을 검토해 주세요
@claude user dashboard 컴포넌트의 TypeError를 수정해 주세요
@claude 이 엔드포인트의 사용자 인증은 어떻게 구현해야 하나요?
```

### 자동 코드 검토

PR이 열릴 때 자동으로 코드 검토를 수행하는 Workflow를 생성합니다:

```yaml theme={null}
name: Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"
        env:
          ANTHROPIC_BASE_URL: "https://api.acedata.cloud"
```

### 정기 작업 자동화

정기적으로 실행되는 자동화 작업을 생성합니다:

```yaml theme={null}
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: "어제의 커밋 요약과 닫히지 않은 Issue의 보고서를 생성해 주세요"
        env:
          ANTHROPIC_BASE_URL: "https://api.acedata.cloud"
```

## Action 매개변수 설명

| 매개변수                | 설명                                       | 필수  |
| ------------------- | ---------------------------------------- | --- |
| `anthropic_api_key` | API 키                                    | 예   |
| `prompt`            | Claude에 대한 지시(텍스트 또는 Skill 예: `/review`) | 아니오 |
| `claude_args`       | Claude Code CLI에 전달할 매개변수                | 아니오 |
| `github_token`      | GitHub Token                             | 아니오 |
| `trigger_phrase`    | 사용자 정의 트리거 구문(기본값 `@claude`)             | 아니오 |

### claude\_args 자주 사용하는 매개변수

```yaml theme={null}
claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929"
```

| 매개변수              | 설명               |
| ----------------- | ---------------- |
| `--max-turns`     | 최대 대화 회차(기본값 10) |
| `--model`         | 사용되는 모델          |
| `--mcp-config`    | MCP 구성 파일 경로     |
| `--allowed-tools` | 허용된 도구(쉼표로 구분)   |
| `--debug`         | 디버그 출력 활성화       |

## 모범 사례

### CLAUDE.md 구성

저장소 루트 디렉토리에 `CLAUDE.md` 파일을 생성하여 코드 스타일 가이드, 검토 기준 및 프로젝트 규칙을 정의하면 Claude가 자동으로 이러한 규칙을 따릅니다.

### 보안 주의 사항

* **절대** API 키를 Workflow 파일에 직접 작성하지 마십시오.
* 항상 GitHub Secrets를 사용하십시오(예: `${{ secrets.ANTHROPIC_API_KEY }}`).
* Action 권한을 최소한의 필요 범위로 제한하십시오.
* 병합 전에 Claude의 제안을 수동으로 검토하십시오.

### 비용 관리

* 명확한 `@claude` 지시를 사용하여 불필요한 API 호출을 줄이십시오.
* 합리적인 `--max-turns`를 설정하여 대화 회차를 제한하십시오.
* Workflow 수준의 타임아웃 시간을 설정하십시오.
* GitHub의 동시 실행 제어를 사용하여 병렬 실행 수를 제한하십시오.

## 자주 묻는 질문

### Claude가 @claude 명령에 응답하지 않나요?

1. Claude GitHub App이 올바르게 설치되었는지 확인하십시오.
2. Workflow가 활성화되어 있는지 확인하십시오.
3. API 키가 저장소 Secret으로 설정되었는지 확인하십시오.
4. 댓글에서 `@claude`를 사용하고 있는지 확인하십시오(비교: `/claude`가 아님).

### 인증 오류?

1. API 키가 유효하고 충분한 권한이 있는지 확인하십시오.
2. 비밀 이름이 올바른지 확인하십시오 (`ANTHROPIC_API_KEY`).
3. `ANTHROPIC_BASE_URL`을 사용한 경우, URL이 올바른지 확인하십시오.

### 잔여 한도를 확인하는 방법은?

[AceData Cloud 콘솔](https://platform.acedata.cloud/console)에 로그인하면 현재 계정의 잔여 한도와 사용 현황을 확인할 수 있습니다.

## 더 알아보기

* 📖 [Claude Code GitHub Actions 공식 문서](https://code.claude.com/docs/en/github-actions)
* 📂 [claude-code-action 저장소](https://github.com/anthropics/claude-code-action)
* 📋 [워크플로우 예시](https://github.com/anthropics/claude-code-action/tree/main/examples)
* 🔧 [AceData Cloud Claude Code 서비스](https://platform.acedata.cloud/documents/claude-messages)
* 💬 질문이 있으시면 플랫폼 고객 서비스에 문의해 주십시오.