Claude Code GitHub Actions

Scopri come integrare Claude Code nel tuo flusso di lavoro di sviluppo con Claude Code GitHub Actions

Claude Code GitHub Actions porta l'automazione basata su AI al tuo flusso di lavoro GitHub. Con una semplice menzione @claude in qualsiasi PR o issue, Claude può analizzare il tuo codice, creare pull request, implementare funzionalità e correggere bug - il tutto seguendo gli standard del tuo progetto. Per le revisioni automatiche pubblicate su ogni PR senza un trigger, vedi GitHub Code Review.

Perché utilizzare Claude Code GitHub Actions?

• Creazione istantanea di PR: Descrivi ciò di cui hai bisogno e Claude crea una PR completa con tutti i cambiamenti necessari
• Implementazione automatica del codice: Trasforma gli issue in codice funzionante con un singolo comando
• Segue i tuoi standard: Claude rispetta le tue linee guida CLAUDE.md e i pattern di codice esistenti
• Configurazione semplice: Inizia in pochi minuti con il nostro installer e la chiave API
• Sicuro per impostazione predefinita: Il tuo codice rimane sui runner di Github

Cosa può fare Claude?

Claude Code fornisce un potente GitHub Action che trasforma il modo in cui lavori con il codice:

Claude Code Action

Questo GitHub Action ti consente di eseguire Claude Code all'interno dei tuoi flussi di lavoro GitHub Actions. Puoi utilizzarlo per costruire qualsiasi flusso di lavoro personalizzato sulla base di Claude Code.

Visualizza repository →

Setup

Configurazione rapida

Il modo più semplice per configurare questa action è attraverso Claude Code nel terminale. Basta aprire claude ed eseguire /install-github-app.

Questo comando ti guiderà attraverso la configurazione dell'app GitHub e dei secret richiesti.

Configurazione manuale

Se il comando /install-github-app non riesce o preferisci una configurazione manuale, segui queste istruzioni di configurazione manuale:

1. Installa l'app GitHub di Claude nel tuo repository: https://github.com/apps/claude

   L'app GitHub di Claude richiede le seguenti autorizzazioni del repository:

   • Contents: Lettura e scrittura (per modificare i file del repository)
   • Issues: Lettura e scrittura (per rispondere agli issue)
   • Pull requests: Lettura e scrittura (per creare PR e spingere i cambiamenti)

   Per ulteriori dettagli sulla sicurezza e le autorizzazioni, vedi la documentazione sulla sicurezza.

2. Aggiungi ANTHROPIC_API_KEY ai tuoi secret del repository (Scopri come utilizzare i secret in GitHub Actions)

3. Copia il file del flusso di lavoro da examples/claude.yml nella cartella .github/workflows/ del tuo repository

Aggiornamento dalla versione Beta

Se stai attualmente utilizzando la versione beta di Claude Code GitHub Actions, ti consigliamo di aggiornare i tuoi flussi di lavoro per utilizzare la versione GA. La nuova versione semplifica la configurazione aggiungendo potenti nuove funzionalità come il rilevamento automatico della modalità.

Cambiamenti essenziali

Tutti gli utenti beta devono apportare questi cambiamenti ai loro file di flusso di lavoro per eseguire l'upgrade:

1. Aggiorna la versione dell'action: Cambia @beta a @v1
2. Rimuovi la configurazione della modalità: Elimina mode: "tag" o mode: "agent" (ora rilevata automaticamente)
3. Aggiorna gli input del prompt: Sostituisci direct_prompt con prompt
4. Sposta le opzioni CLI: Converti max_turns, model, custom_instructions, ecc. in claude_args

Breaking Changes Reference

Esempio Prima e Dopo

Versione beta:

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Follow our coding standards"
    max_turns: "10"
    model: "claude-sonnet-4-6"

Versione GA (v1.0):

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "Follow our coding standards"
      --max-turns 10
      --model claude-sonnet-4-6

Esempi di casi d'uso

Claude Code GitHub Actions può aiutarti con una varietà di attività. La directory degli esempi contiene flussi di lavoro pronti all'uso per diversi scenari.

Flusso di lavoro di base

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 }}
          # Responds to @claude mentions in comments

Utilizzo di skills

L'input prompt accetta un'invocazione di skill così come testo semplice:

• Per una skill nella directory .claude/skills/ del vostro repository, eseguite actions/checkout prima del passo dell'azione e passate /skill-name.
• Per una skill inclusa in un plugin, installate il plugin con gli input plugin_marketplaces e plugins e passate lo /plugin-name:skill-name con namespace.

Il seguente flusso di lavoro installa il plugin code-review ed esegue la sua skill su ogni pull request nuova o aggiornata:

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 }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

Automazione personalizzata con prompt

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: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model opus"

Casi d'uso comuni

Nei commenti di issue o PR:

@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 analizzerà automaticamente il contesto e risponderà in modo appropriato.

Best practices

Configurazione CLAUDE.md

Crea un file CLAUDE.md nella radice del tuo repository per definire le linee guida dello stile di codice, i criteri di revisione, le regole specifiche del progetto e i pattern preferiti. Questo file guida la comprensione di Claude degli standard del tuo progetto.

Considerazioni sulla sicurezza

Per una guida completa sulla sicurezza inclusa autorizzazioni, autenticazione e best practices, vedi la documentazione sulla sicurezza di Claude Code Action.

Utilizza sempre GitHub Secrets per le chiavi API:

• Aggiungi la tua chiave API come secret del repository denominato ANTHROPIC_API_KEY
• Fai riferimento ad essa nei flussi di lavoro: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
• Limita le autorizzazioni dell'action solo a ciò che è necessario
• Rivedi i suggerimenti di Claude prima di eseguire il merge

Utilizza sempre GitHub Secrets (ad esempio, ${{ secrets.ANTHROPIC_API_KEY }}) piuttosto che hardcodare le chiavi API direttamente nei tuoi file di flusso di lavoro.

Ottimizzazione delle prestazioni

Utilizza i template di issue per fornire contesto, mantieni il tuo CLAUDE.md conciso e focalizzato, e configura timeout appropriati per i tuoi flussi di lavoro.

Costi CI

Quando utilizzi Claude Code GitHub Actions, tieni presente i costi associati:

Costi di GitHub Actions:

• Claude Code viene eseguito su runner ospitati da GitHub, che consumano i tuoi minuti di GitHub Actions
• Vedi la documentazione sulla fatturazione di GitHub per i dettagli sui prezzi e i limiti di minuti

Costi API:

• Ogni interazione di Claude consuma token API in base alla lunghezza dei prompt e delle risposte
• L'utilizzo dei token varia in base alla complessità dell'attività e alla dimensione della codebase
• Vedi la pagina dei prezzi di Claude per i tassi di token attuali

Suggerimenti per l'ottimizzazione dei costi:

• Utilizza comandi specifici @claude per ridurre le chiamate API non necessarie
• Configura --max-turns appropriato in claude_args per prevenire iterazioni eccessive
• Imposta timeout a livello di flusso di lavoro per evitare job fuori controllo
• Considera l'utilizzo dei controlli di concorrenza di GitHub per limitare le esecuzioni parallele

Esempi di configurazione

Claude Code Action v1 semplifica la configurazione con parametri unificati:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Your instructions here" # Optional
    claude_args: "--max-turns 5" # Optional CLI arguments

Caratteristiche principali:

• Interfaccia prompt unificata - Utilizza prompt per tutte le istruzioni
• Skills - Richiama skills installate direttamente dal prompt
• Passthrough CLI - Qualsiasi argomento CLI di Claude Code tramite claude_args
• Trigger flessibili - Funziona con qualsiasi evento GitHub

Visita la directory degli esempi per i file di flusso di lavoro completi.

Utilizzo con Amazon Bedrock e Google Vertex AI

Per ambienti aziendali, puoi utilizzare Claude Code GitHub Actions con la tua infrastruttura cloud. Questo approccio ti dà il controllo sulla residenza dei dati e sulla fatturazione mantenendo la stessa funzionalità.

Prerequisiti

Prima di configurare Claude Code GitHub Actions con i provider cloud, hai bisogno di:

Per Google Cloud Vertex AI:

1. Un progetto Google Cloud con Vertex AI abilitato
2. Workload Identity Federation configurato per GitHub Actions
3. Un account di servizio con le autorizzazioni richieste
4. Un'app GitHub (consigliato) o utilizza il GITHUB_TOKEN predefinito

Per Amazon Bedrock:

1. Un account AWS con Amazon Bedrock abilitato
2. GitHub OIDC Identity Provider configurato in AWS
3. Un ruolo IAM con autorizzazioni Bedrock
4. Un'app GitHub (consigliato) o utilizza il GITHUB_TOKEN predefinito

name: Claude PR Action

permissions:
contents: write
pull-requests: write
issues: write
id-token: write

on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]

jobs:
claude-pr:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
runs-on: ubuntu-latest
env:
AWS_REGION: us-west-2
steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Generate GitHub App token
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.APP_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}

- name: Configure AWS Credentials (OIDC)
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
aws-region: us-west-2

- uses: anthropics/claude-code-action@v1
with:
github_token: ${{ steps.app-token.outputs.token }}
use_bedrock: "true"
claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'

name: Claude PR Action

permissions:
contents: write
pull-requests: write
issues: write
id-token: write

on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]

jobs:
claude-pr:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Generate GitHub App token
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.APP_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}

- name: Authenticate to Google Cloud
id: auth
uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

- uses: anthropics/claude-code-action@v1
with:
github_token: ${{ steps.app-token.outputs.token }}
trigger_phrase: "@claude"
use_vertex: "true"
claude_args: '--model claude-sonnet-4-5@20250929 --max-turns 10'
env:
ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
CLOUD_ML_REGION: us-east5
VERTEX_REGION_CLAUDE_4_5_SONNET: us-east5

Troubleshooting

Claude non risponde ai comandi @claude

Verifica che l'app GitHub sia installata correttamente, controlla che i flussi di lavoro siano abilitati, assicurati che la chiave API sia impostata nei secret del repository e conferma che il commento contenga @claude (non /claude).

CI non in esecuzione sui commit di Claude

Assicurati di utilizzare l'app GitHub o l'app personalizzata (non l'utente Actions), controlla che i trigger del flusso di lavoro includano gli eventi necessari e verifica che le autorizzazioni dell'app includano i trigger CI.

Errori di autenticazione

Conferma che la chiave API sia valida e abbia autorizzazioni sufficienti. Per Bedrock/Vertex, controlla la configurazione delle credenziali e assicurati che i secret siano denominati correttamente nei flussi di lavoro.

Configurazione avanzata

Parametri dell'action

Claude Code Action v1 utilizza una configurazione semplificata:

*Prompt è opzionale - quando omesso per i commenti di issue/PR, Claude risponde alla frase trigger
**Richiesto per l'API Claude diretta, non per Bedrock/Vertex

Passa argomenti CLI

Il parametro claude_args accetta qualsiasi argomento CLI di Claude Code:

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

Argomenti comuni:

• --max-turns: Numero massimo di turni di conversazione (predefinito: 10)
• --model: Modello da utilizzare (ad es. claude-sonnet-4-6)
• --mcp-config: Percorso della configurazione MCP
• --allowedTools: Elenco separato da virgole degli strumenti consentiti. L'alias --allowed-tools funziona anche.
• --debug: Abilita l'output di debug

Metodi di integrazione alternativi

Mentre il comando /install-github-app è l'approccio consigliato, puoi anche:

• Custom GitHub App: Per le organizzazioni che necessitano di nomi utente personalizzati o flussi di autenticazione personalizzati. Crea la tua app GitHub con le autorizzazioni richieste (contents, issues, pull requests) e utilizza l'action actions/create-github-app-token per generare token nei tuoi flussi di lavoro.
• Manual GitHub Actions: Configurazione diretta del flusso di lavoro per la massima flessibilità
• MCP Configuration: Caricamento dinamico dei server Model Context Protocol

Vedi la documentazione di Claude Code Action per guide dettagliate su autenticazione, sicurezza e configurazione avanzata.

Personalizzazione del comportamento di Claude

Puoi configurare il comportamento di Claude in due modi:

1. CLAUDE.md: Definisci gli standard di codifica, i criteri di revisione e le regole specifiche del progetto in un file CLAUDE.md nella radice del tuo repository. Claude seguirà queste linee guida quando crea PR e risponde alle richieste. Consulta la nostra documentazione Memory per ulteriori dettagli.
2. Custom prompts: Utilizza il parametro prompt nel file del flusso di lavoro per fornire istruzioni specifiche del flusso di lavoro. Questo ti consente di personalizzare il comportamento di Claude per diversi flussi di lavoro o attività.

Claude seguirà queste linee guida quando crea PR e risponde alle richieste.