> ## 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.

# Tutorial de Uso do Claude Code GitHub Actions

> Claude Code 集成指南 - Ace Data Cloud

Claude Code é uma ferramenta de **Programação Agentic** lançada pela Anthropic, também conhecida como um dos agentes de programação mais poderosos do mundo. O Claude Code GitHub Actions pode integrar a capacidade de programação da IA ao seu fluxo de trabalho do GitHub; basta mencionar `@claude` em um PR ou Issue para que o Claude analise automaticamente o código, crie PRs, implemente funcionalidades e corrija bugs.

Este documento descreve principalmente como configurar e usar o Claude Code GitHub Actions através do serviço de proxy da AceData Cloud.

## Processo de Solicitação

Para usar o Claude Code, primeiro você pode acessar a [página de serviços do Claude Messages](https://platform.acedata.cloud/documents/claude-messages) e clicar no botão "Acquire" para obter as credenciais necessárias para a solicitação:

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

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login; após o registro e login, você será retornado à página atual.

Na primeira solicitação, haverá um crédito gratuito disponível para que você possa experimentar o serviço Claude Code sem custo.

## Características

* **Criação instantânea de PR**: descreva a necessidade, e o Claude criará automaticamente um Pull Request completo.
* **Implementação automática de código**: mencione `@claude` em um Issue, e ele transformará o Issue em código executável.
* **Conformidade com as normas do projeto**: lê automaticamente o `CLAUDE.md`, seguindo seu estilo de código e normas do projeto.
* **Seguro e confiável**: o código é executado no Runner do GitHub, garantindo a segurança dos dados.

## Etapas de Configuração

### Passo Um: Instalar o App do Claude no GitHub

Acesse [https://github.com/apps/claude](https://github.com/apps/claude) e instale o App do Claude no seu repositório.

![Página de Instalação do App do GitHub Claude](https://cdn.acedata.cloud/ba4b8df66d.png)

Este App requer as seguintes permissões do repositório:

| Permissão         | Nível        | Descrição                         |
| ----------------- | ------------ | --------------------------------- |
| **Contents**      | Read & Write | Modificar arquivos do repositório |
| **Issues**        | Read & Write | Responder a Issues                |
| **Pull requests** | Read & Write | Criar PR e enviar alterações      |

### Passo Dois: Adicionar a Chave da API

Adicione a chave da API da AceData Cloud como um Secret do repositório:

1. Acesse **Settings** do repositório → **Secrets and variables** → **Actions**
2. Clique em **New repository secret**
3. No campo Name, preencha `ANTHROPIC_API_KEY`, e no campo Value, insira o token da API que você obteve na AceData Cloud
4. Clique em **Add secret** para salvar

> **Dica**: O token da API pode ser visualizado no [console da AceData Cloud](https://platform.acedata.cloud/console).

### Passo Três: Criar o Arquivo de Workflow

Crie o arquivo `.github/workflows/claude.yml` no repositório:

```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 }}
```

Se precisar usar o endpoint da API de proxy da AceData Cloud, também será necessário definir a variável de ambiente no 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"
```

## Modo de Uso

### Usando em Comentários de Issue ou PR

Após a configuração, em qualquer comentário de Issue ou PR, mencione `@claude`, e o Claude responderá automaticamente:

```
@claude implemente a funcionalidade com base na descrição deste Issue
@claude revise a segurança do código deste PR
@claude corrija o TypeError no componente do painel do usuário
@claude como deve ser implementada a autenticação do usuário neste endpoint?
```

### Revisão Automática de Código

Crie um Workflow que execute automaticamente a revisão de código ao abrir um PR:

```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"
```

### Automação de Tarefas Agendadas

Crie uma tarefa automatizada que execute em um horário programado:

```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: "Gerar um resumo dos commits de ontem e um relatório dos Issues não fechados"
        env:
          ANTHROPIC_BASE_URL: "https://api.acedata.cloud"
```

## Descrição dos Parâmetros da Action

| Parâmetro           | Descrição                                               | Obrigatório |
| ------------------- | ------------------------------------------------------- | ----------- |
| `anthropic_api_key` | Chave da API                                            | Sim         |
| `prompt`            | Instrução para o Claude (texto ou Skill como `/review`) | Não         |
| `claude_args`       | Parâmetros passados para o CLI do Claude Code           | Não         |
| `github_token`      | Token do GitHub                                         | Não         |
| `trigger_phrase`    | Frase de ativação personalizada (padrão `@claude`)      | Não         |

### Parâmetros Comuns de claude\_args

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

| Parâmetro         | Descrição                                      |
| ----------------- | ---------------------------------------------- |
| `--max-turns`     | Número máximo de turnos de diálogo (padrão 10) |
| `--model`         | Modelo a ser utilizado                         |
| `--mcp-config`    | Caminho do arquivo de configuração MCP         |
| `--allowed-tools` | Ferramentas permitidas (separadas por vírgula) |
| `--debug`         | Ativar saída de depuração                      |

## Melhores Práticas

### Configurar o CLAUDE.md

Crie um arquivo `CLAUDE.md` no diretório raiz do repositório, definindo diretrizes de estilo de código, padrões de revisão e normas do projeto; o Claude seguirá automaticamente essas regras.

### Considerações de Segurança

* **Nunca** escreva a chave da API diretamente no arquivo de Workflow.
* Sempre use Secrets do GitHub (como `${{ secrets.ANTHROPIC_API_KEY }}`).
* Limite as permissões da Action ao mínimo necessário.
* Revise manualmente as sugestões do Claude antes de mesclar.

### Controle de Custos

* Use instruções claras de `@claude` para reduzir chamadas desnecessárias à API.
* Configure um limite razoável de `--max-turns` para o número de turnos de diálogo.
* Defina um tempo limite em nível de Workflow.
* Use o controle de concorrência do GitHub para limitar o número de execuções paralelas.

## Perguntas Frequentes

### O Claude não respondeu ao comando @claude?

1. Verifique se o App do Claude no GitHub está instalado corretamente.
2. Verifique se o Workflow está habilitado.
3. Confirme se a chave da API está configurada como um Secret do repositório.
4. Certifique-se de que está usando `@claude` nos comentários (não `/claude`).

### Erro de autenticação?

1. Confirme se a chave da API é válida e tem permissões suficientes
2. Verifique se o nome do Secret está correto (`ANTHROPIC_API_KEY`)
3. Se estiver usando `ANTHROPIC_BASE_URL`, confirme se a URL está correta

### Como verificar o saldo restante?

Faça login no [Painel de Controle AceData Cloud](https://platform.acedata.cloud/console) para visualizar o saldo restante e o uso atual da conta.

## Saiba mais

* 📖 [Documentação oficial do Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions)
* 📂 [Repositório claude-code-action](https://github.com/anthropics/claude-code-action)
* 📋 [Exemplo de Workflow](https://github.com/anthropics/claude-code-action/tree/main/examples)
* 🔧 [Serviço Claude Code da AceData Cloud](https://platform.acedata.cloud/documents/claude-messages)
* 💬 Se tiver alguma dúvida, sinta-se à vontade para entrar em contato conosco através do suporte da plataforma