Claude Code GitHub Actions

• Code Review: revisão automática em cada pull request, sem escrever um fluxo de trabalho
• Claude Code na web: sessões de Claude Code que executam em infraestrutura em nuvem em vez de sua máquina
• Claude Agent SDK: automação personalizada fora do GitHub Actions. A Claude Code GitHub Action é construída sobre o SDK
• GitHub Enterprise Server: Claude Code com GitHub auto-hospedado

​

Configuração

• Configuração rápida: execute /install-github-app a partir do Claude Code. Claude Code instala a GitHub App, adiciona seu secret de autenticação e prepara o pull request de fluxo de trabalho para você
• Configuração manual: instale a app, adicione o secret e copie o arquivo de fluxo de trabalho em seu repositório você mesmo. Use este caminho quando você não executa Claude Code localmente, quando o comando falha ou quando você quer controle total dos arquivos de fluxo de trabalho

​

Configuração rápida

• Se Claude Code já tiver uma chave de API, ele reutiliza essa chave e oferece manter o secret ANTHROPIC_API_KEY existente do repositório se um já estiver definido
• Caso contrário, escolha entre criar um token de longa duração com sua assinatura Claude e colar uma chave de API

• Execute /install-github-app novamente. Quando o repositório já tiver um claude.yml, selecione Update workflow file with latest version. Claude Code faz push de cópias novas dos arquivos de fluxo de trabalho para um novo branch e abre o pull request, igual a uma primeira instalação.
• Adicione o argumento --comment e a linha claude_args do exemplo de fluxo de trabalho de revisão ao arquivo verificado você mesmo, o que mantém quaisquer outras edições que você fez nele.

​

Configuração manual

​

Configurar para uma organização

• Instale a Claude GitHub App uma vez no nível da organização, escolhendo todos os repositórios ou uma lista selecionada
• Armazene o secret de autenticação como um secret de Actions no nível da organização para que cada repositório não precise de sua própria cópia
• Adicione o arquivo de fluxo de trabalho a cada repositório que deve executar a Claude Code GitHub Action, ou defina o job uma vez como um fluxo de trabalho reutilizável que cada repositório chama

• anthropic_federation_rule_id: o ID da regra de federação, fdrl_...
• anthropic_organization_id: seu ID de organização Anthropic
• anthropic_service_account_id: o ID da conta de serviço, svac_.... Opcional, já que a regra de federação que você cria no Console já tem como alvo uma conta de serviço
• anthropic_workspace_id: o ID do workspace, wrkspc_.... Opcional quando a regra de federação tem como alvo um único workspace

​

Desinstalar

• Arquivos de fluxo de trabalho: delete os fluxos de trabalho que usam anthropics/claude-code-action de .github/workflows/. Se você usou configuração rápida, procure por claude.yml e, se você selecionou o fluxo de trabalho de revisão, claude-code-review.yml. Com os fluxos de trabalho deletados, a Claude Code GitHub Action não é mais executada
• Secrets: delete o secret ANTHROPIC_API_KEY ou CLAUDE_CODE_OAUTH_TOKEN do repositório e dos secrets de Actions no nível da organização se você compartilhou entre repositórios. Se você deletar um secret, a credencial que ele continha permanece válida. Para desativar uma chave de API completamente, também delete a chave no Claude Console
• GitHub App: desinstale a Claude GitHub App nas configurações do seu repositório ou organização em GitHub Apps, mas apenas se você não a usar para outro recurso Claude, como Code Review ou web auto-fix

​

Permissões da GitHub App

​

Modos interativo e de automação

• Modo interativo: quando o fluxo de trabalho não fornece entrada prompt, Claude aguarda a frase de gatilho, @claude por padrão, em um comentário de issue ou pull request, em uma revisão de pull request ou no corpo ou título de uma issue recém-aberta, então responde a essa solicitação. Progresso e resultados aparecem como um comentário na issue ou PR que acionou.
• Modo de automação: quando o fluxo de trabalho fornece uma entrada prompt, Claude é executado sem aguardar uma menção, sujeito apenas às verificações sobre quem pode acionar execuções. Por padrão, os resultados aparecem no log de execução do fluxo de trabalho em vez de um comentário. Claude pode postar na issue ou pull request quando o prompt o direciona e ele tem uma ferramenta que pode postar, como no exemplo de code-review.

​

Quem pode acionar execuções

• Acesso de escrita: em eventos de issue e pull request, o usuário que aciona deve ter acesso de escrita ao repositório. Para permitir usuários específicos sem acesso de escrita, defina allowed_non_write_users e passe sua própria entrada github_token. Eventos que nenhum usuário cria, como um gatilho schedule, pulam essa verificação.
• Ator humano: em cada evento, a Claude Code GitHub Action rejeita um ator bot a menos que você o liste em allowed_bots, o que impede que bots acionem Claude em um loop. Essa verificação também se aplica a execuções agendadas, que o GitHub atribui a um usuário do repositório, geralmente aquele que alterou pela última vez o cronograma cron do fluxo de trabalho. Se esse usuário for um bot, liste-o em allowed_bots.

​

Exemplos de casos de uso

​

Responder a menções @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: necessário para a autenticação padrão da GitHub App da Claude Code GitHub Action
• actions: read: permite que Claude leia resultados de CI em PRs
• actions/checkout: fornece a Claude uma cópia local do repositório para trabalhar
• if: impede que runners iniciem em comentários que não mencionam @claude. A Claude Code GitHub Action também verifica a frase de gatilho em si antes de responder

@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

​

Executar uma skill

• Para uma skill no diretório .claude/skills/ do seu repositório, execute actions/checkout antes da etapa anthropics/claude-code-action para que os arquivos de skill estejam disponíveis no runner, então passe /skill-name como o prompt.
• Para uma skill empacotada em um plugin, instale o plugin com as entradas plugin_marketplaces e plugins, então passe o /plugin-name:skill-name com namespace como o prompt. A entrada plugins recebe plugin-name@marketplace-name, onde o nome do marketplace vem do próprio manifesto do marketplace em vez de sua URL de repositório.

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 publica sua revisão no pull request, como um comentário inline em cada issue que encontra ou como um comentário de resumo quando não encontra nenhum. Sem ele, Claude não publica nada, e você lê os achados no log de execução do fluxo de trabalho.
• claude_args: mantenha esta linha mesmo que o frontmatter allowed-tools próprio da skill nomeie a mesma ferramenta, porque a Claude Code GitHub Action inicia o servidor MCP que publica comentários inline apenas quando --allowedTools em claude_args o nomeia.

​

Executar em um cronograma

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"

​

Melhores práticas

​

Defina padrões de projeto em CLAUDE.md

​

Proteja suas credenciais

​

Gerencie custos

• Minutos do GitHub Actions: a Claude Code GitHub Action é executada em runners hospedados pelo GitHub, que consomem seus minutos do GitHub Actions. Consulte a documentação de faturamento do GitHub para preços e limites de minutos.
• Tokens de API: cada interação consome tokens com base no comprimento de prompts e respostas, complexidade da tarefa e tamanho da base de código. Consulte a página de preços do Claude para taxas de token atuais. Se você se autenticar com um token OAuth, as execuções usam sua assinatura Claude em vez de faturamento de API.

• Escreva solicitações específicas de @claude para que Claude precise de menos turnos para terminar
• Use templates de issue para fornecer contexto antecipadamente
• Mantenha seu CLAUDE.md conciso, já que Claude o lê em cada execução
• Defina --max-turns em claude_args para limitar iterações
• Defina timeouts no nível do fluxo de trabalho para evitar jobs descontrolados
• Use controles de concorrência do GitHub para limitar execuções paralelas

​

Use um provedor de nuvem

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

​

Solução de problemas

​

Claude não responde aos comandos @claude

• Verifique se a GitHub App está instalada no repositório
• Verifique se os fluxos de trabalho estão habilitados para o repositório
• Garanta que sua chave de API ou token OAuth esteja definido em secrets do repositório
• Confirme que o comentário contém @claude como uma palavra completa, não /claude ou @claude-bot
• Confirme que o usuário que comenta tem acesso de escrita ao repositório. Consulte Quem pode acionar execuções para as exceções

​

CI não está sendo executado nos commits de Claude

• O GitHub não aciona fluxos de trabalho em commits feitos com o GITHUB_TOKEN padrão. Se você passar github_token: ${{ secrets.GITHUB_TOKEN }} para a Claude Code GitHub Action, remova-o para que ele se autentique como a Claude GitHub App, ou passe um token de app personalizado em vez disso
• Verifique se os gatilhos do fluxo de trabalho de CI incluem os eventos que os pushes de Claude produzem, como push ou pull_request

​

Erros de autenticação

• Confirme que a chave de API ou token OAuth é válido testando-o localmente com claude antes de depurar o fluxo de trabalho
• Para Bedrock, Agent Platform e Foundry, consulte a seção de solução de problemas da página do provedor de nuvem

​

Configuração avançada

​

Parâmetros da Action

​

Passe argumentos de CLI

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

• --max-turns: limita o número de turnos de conversa
• --model: modelo a usar, por exemplo claude-sonnet-5. Sem este argumento, a Claude Code GitHub Action usa o modelo padrão do Claude Code
• --mcp-config: caminho para configuração MCP
• --allowedTools: lista separada por vírgula de ferramentas permitidas. O alias --allowed-tools também funciona
• --debug: habilita saída de debug

​

Atualizar da versão beta

1. Altere @beta para @v1 na linha uses
2. Remova a entrada mode, já que a Claude Code GitHub Action agora detecta o modo automaticamente
3. Substitua direct_prompt por prompt
4. Mova opções de CLI como max_turns e model para claude_args. custom_instructions não tem um sinalizador de mesmo nome e se torna --append-system-prompt

​

Próximos passos

• Use Claude Code GitHub Actions com provedores de nuvem: rotear inferência através de Amazon Bedrock, Google Cloud’s Agent Platform ou Microsoft Foundry
• Referência de configuração: a lista completa de entradas da action
• Diretório de exemplos: fluxos de trabalho prontos para uso em mais cenários
• Code Review: revisão automática de pull request sem manter um arquivo de fluxo de trabalho