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 - tutto seguendo gli standard del tuo progetto.
Claude Code GitHub Actions è costruito sopra il Claude Code SDK, che abilita l’integrazione programmatica di Claude Code nelle tue applicazioni. Puoi usare l’SDK per costruire flussi di lavoro di automazione personalizzati oltre GitHub Actions.
Perché usare Claude Code GitHub Actions?
- Creazione istantanea di PR: Descrivi quello che ti serve, e Claude crea una PR completa con tutte le modifiche necessarie
- Implementazione automatizzata del codice: Trasforma le 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 una potente GitHub Action che trasforma il modo in cui lavori con il codice:
Claude Code Action
Questa GitHub Action ti permette di eseguire Claude Code all’interno dei tuoi flussi di lavoro GitHub Actions. Puoi usarla per costruire qualsiasi flusso di lavoro personalizzato sopra Claude Code.
Configurazione
Configurazione rapida
Il modo più semplice per configurare questa action è attraverso Claude Code nel terminale. Apri semplicemente claude ed esegui /install-github-app
.
Questo comando ti guiderà attraverso la configurazione dell’app GitHub e dei segreti richiesti.
- Devi essere un amministratore del repository per installare l’app GitHub e aggiungere segreti - Questo metodo di avvio rapido è disponibile solo per gli utenti diretti dell’API Anthropic. Se stai usando AWS Bedrock o Google Vertex AI, consulta la sezione Uso con AWS Bedrock & Google Vertex AI.
Configurazione manuale
Se il comando /install-github-app
fallisce o preferisci la configurazione manuale, segui queste istruzioni di configurazione manuale:
- Installa l’app GitHub Claude nel tuo repository: https://github.com/apps/claude
- Aggiungi ANTHROPIC_API_KEY ai segreti del tuo repository (Scopri come usare i segreti in GitHub Actions)
- Copia il file del flusso di lavoro da examples/claude.yml nella cartella
.github/workflows/
del tuo repository
Dopo aver completato la configurazione rapida o manuale, testa l’action
taggando @claude
in un commento di issue o PR!
Aggiornamento dalla Beta
Claude Code GitHub Actions v1.0 introduce modifiche che rompono la compatibilità che richiedono l’aggiornamento dei tuoi file di flusso di lavoro per passare alla v1.0 dalla versione beta.
Se stai attualmente usando la versione beta di Claude Code GitHub Actions, raccomandiamo di aggiornare i tuoi flussi di lavoro per usare la versione GA. La nuova versione semplifica la configurazione aggiungendo potenti nuove funzionalità come il rilevamento automatico della modalità.
Modifiche essenziali
Tutti gli utenti beta devono apportare queste modifiche ai loro file di flusso di lavoro per aggiornare:
- Aggiorna la versione dell’action: Cambia
@beta
in@v1
- Rimuovi la configurazione della modalità: Elimina
mode: "tag"
omode: "agent"
(ora rilevato automaticamente) - Aggiorna gli input del prompt: Sostituisci
direct_prompt
conprompt
- Sposta le opzioni CLI: Converti
max_turns
,model
,custom_instructions
, ecc. inclaude_args
Riferimento delle Modifiche che Rompono la Compatibilità
Vecchio Input Beta | Nuovo Input v1.0 |
---|---|
mode | (Rimosso - rilevato automaticamente) |
direct_prompt | prompt |
override_prompt | prompt con variabili GitHub |
custom_instructions | claude_args: --system-prompt |
max_turns | claude_args: --max-turns |
model | claude_args: --model |
allowed_tools | claude_args: --allowedTools |
disallowed_tools | claude_args: --disallowedTools |
claude_env | settings formato JSON |
Esempio Prima e Dopo
Versione beta:
Versione GA (v1.0):
L’action ora rileva automaticamente se eseguire in modalità interattiva (risponde alle menzioni @claude
) o modalità automazione (esegue immediatamente con un prompt) basandosi sulla tua configurazione.
Esempi di casi d’uso
Claude Code GitHub Actions può aiutarti con una varietà di compiti. La directory degli esempi contiene flussi di lavoro pronti all’uso per diversi scenari.
Flusso di lavoro base
Uso dei comandi slash
Automazione personalizzata con prompt
Casi d’uso comuni
Nei commenti di issue o PR:
Claude analizzerà automaticamente il contesto e risponderà appropriatamente.
Migliori pratiche
Configurazione CLAUDE.md
Crea un file CLAUDE.md
nella radice del tuo repository per definire linee guida di stile del codice, criteri di revisione, regole specifiche del progetto e pattern preferiti. Questo file guida la comprensione di Claude degli standard del tuo progetto.
Considerazioni sulla sicurezza
Usa sempre i GitHub Secrets per le chiavi API:
- Aggiungi la tua chiave API come segreto del repository chiamato
ANTHROPIC_API_KEY
- Referenziala nei flussi di lavoro:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
- Limita i permessi dell’action solo a quello che è necessario
- Rivedi i suggerimenti di Claude prima del merge
Usa sempre i GitHub Secrets (es., ${{ secrets.ANTHROPIC_API_KEY }}
) piuttosto che codificare direttamente le chiavi API nei tuoi file di flusso di lavoro.
Ottimizzazione delle prestazioni
Usa 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 usi Claude Code GitHub Actions, sii consapevole dei costi associati:
Costi GitHub Actions:
- Claude Code viene eseguito sui runner ospitati da GitHub, che consumano i tuoi minuti GitHub Actions
- Vedi la documentazione di fatturazione di GitHub per prezzi dettagliati e limiti di minuti
Costi API:
- Ogni interazione con Claude consume token API basati sulla lunghezza di prompt e risposte
- L’uso dei token varia in base alla complessità del compito e alla dimensione del codebase
- Vedi la pagina dei prezzi di Claude per le tariffe attuali dei token
Suggerimenti per l’ottimizzazione dei costi:
- Usa comandi
@claude
specifici per ridurre chiamate API non necessarie - Configura
--max-turns
appropriato inclaude_args
per prevenire iterazioni eccessive - Imposta timeout a livello di flusso di lavoro per evitare job che si bloccano
- Considera l’uso dei controlli di concorrenza di GitHub per limitare le esecuzioni parallele
Esempi di configurazione
La Claude Code Action v1 semplifica la configurazione con parametri unificati:
Caratteristiche chiave:
- Interfaccia prompt unificata - Usa
prompt
per tutte le istruzioni - Comandi slash - Prompt precostruiti come
/review
o/fix
- Passthrough CLI - Qualsiasi argomento CLI di Claude Code tramite
claude_args
- Trigger flessibili - Funziona con qualsiasi evento GitHub
Visita la directory degli esempi per file di flusso di lavoro completi.
Quando risponde ai commenti di issue o PR, Claude risponde automaticamente alle menzioni @claude. Per altri eventi, usa il parametro prompt
per fornire istruzioni.
Uso con AWS Bedrock & Google Vertex AI
Per ambienti enterprise, puoi usare Claude Code GitHub Actions con la tua infrastruttura cloud. Questo approccio ti dà controllo sulla residenza dei dati e sulla fatturazione mantenendo la stessa funzionalità.
Prerequisiti
Prima di configurare Claude Code GitHub Actions con provider cloud, hai bisogno di:
Per Google Cloud Vertex AI:
- Un Progetto Google Cloud con Vertex AI abilitato
- Workload Identity Federation configurato per GitHub Actions
- Un account di servizio con i permessi richiesti
- Un’App GitHub (raccomandato) o usa il GITHUB_TOKEN predefinito
Per AWS Bedrock:
- Un account AWS con Amazon Bedrock abilitato
- Provider di Identità OIDC GitHub configurato in AWS
- Un ruolo IAM con permessi Bedrock
- Un’App GitHub (raccomandato) o usa il GITHUB_TOKEN predefinito
Crea un'App GitHub personalizzata (Raccomandato per Provider 3P)
Per il miglior controllo e sicurezza quando usi provider 3P come Vertex AI o Bedrock, raccomandiamo di creare la tua App GitHub:
- Vai su https://github.com/settings/apps/new
- Compila le informazioni di base:
- Nome App GitHub: Scegli un nome unico (es., “YourOrg Claude Assistant”)
- URL Homepage: Il sito web della tua organizzazione o l’URL del repository
- Configura le impostazioni dell’app:
- Webhooks: Deseleziona “Active” (non necessario per questa integrazione)
- Imposta i permessi richiesti:
- Permessi repository:
- Contents: Read & Write
- Issues: Read & Write
- Pull requests: Read & Write
- Permessi repository:
- Clicca “Create GitHub App”
- Dopo la creazione, clicca “Generate a private key” e salva il file
.pem
scaricato - Annota il tuo App ID dalla pagina delle impostazioni dell’app
- Installa l’app nel tuo repository:
- Dalla pagina delle impostazioni della tua app, clicca “Install App” nella barra laterale sinistra
- Seleziona il tuo account o organizzazione
- Scegli “Only select repositories” e seleziona il repository specifico
- Clicca “Install”
- Aggiungi la chiave privata come segreto al tuo repository:
- Vai nelle Impostazioni del tuo repository → Secrets and variables → Actions
- Crea un nuovo segreto chiamato
APP_PRIVATE_KEY
con il contenuto del file.pem
- Aggiungi l’App ID come segreto:
- Crea un nuovo segreto chiamato
APP_ID
con l’ID della tua App GitHub
Questa app sarà usata con l’action actions/create-github-app-token per generare token di autenticazione nei tuoi flussi di lavoro.
Alternativa per API Anthropic o se non vuoi configurare la tua app Github: Usa l’app ufficiale Anthropic:
- Installa da: https://github.com/apps/claude
- Nessuna configurazione aggiuntiva necessaria per l’autenticazione
Configura l'autenticazione del provider cloud
Scegli il tuo provider cloud e configura l’autenticazione sicura:
Aggiungi Segreti Richiesti
Aggiungi i seguenti segreti al tuo repository (Settings → Secrets and variables → Actions):
Per API Anthropic (Diretta):
-
Per Autenticazione API:
ANTHROPIC_API_KEY
: La tua chiave API Anthropic da console.anthropic.com
-
Per App GitHub (se usi la tua app):
APP_ID
: L’ID della tua App GitHubAPP_PRIVATE_KEY
: Il contenuto della chiave privata (.pem)
Per Google Cloud Vertex AI
-
Per Autenticazione GCP:
GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT
-
Per App GitHub (se usi la tua app):
APP_ID
: L’ID della tua App GitHubAPP_PRIVATE_KEY
: Il contenuto della chiave privata (.pem)
Per AWS Bedrock
-
Per Autenticazione AWS:
AWS_ROLE_TO_ASSUME
-
Per App GitHub (se usi la tua app):
APP_ID
: L’ID della tua App GitHubAPP_PRIVATE_KEY
: Il contenuto della chiave privata (.pem)
Crea file di flusso di lavoro
Crea file di flusso di lavoro GitHub Actions che si integrano con il tuo provider cloud. Gli esempi sotto mostrano configurazioni complete sia per AWS Bedrock che per Google Vertex AI:
Risoluzione dei problemi
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 segreti del repository, e conferma che il commento contenga @claude
(non /claude
).
CI non viene eseguito sui commit di Claude
Assicurati di usare l’App GitHub o app personalizzata (non l’utente Actions), controlla che i trigger del flusso di lavoro includano gli eventi necessari, e verifica che i permessi dell’app includano i trigger CI.
Errori di autenticazione
Conferma che la chiave API sia valida e abbia permessi sufficienti. Per Bedrock/Vertex, controlla la configurazione delle credenziali e assicurati che i segreti siano nominati correttamente nei flussi di lavoro.
Configurazione avanzata
Parametri dell’action
La Claude Code Action v1 usa una configurazione semplificata:
Parametro | Descrizione | Richiesto |
---|---|---|
prompt | Istruzioni per Claude (testo o comando slash) | No* |
claude_args | Argomenti CLI passati a Claude Code | No |
anthropic_api_key | Chiave API Anthropic | Sì** |
github_token | Token GitHub per accesso API | No |
trigger_phrase | Frase trigger personalizzata (predefinito: “@claude”) | No |
use_bedrock | Usa AWS Bedrock invece dell’API Anthropic | No |
use_vertex | Usa Google Vertex AI invece dell’API Anthropic | No |
*Prompt è opzionale - quando omesso per commenti issue/PR, Claude risponde alla frase trigger
**Richiesto per API Anthropic diretta, non per Bedrock/Vertex
Uso di claude_args
Il parametro claude_args
accetta qualsiasi argomento CLI di Claude Code:
Argomenti comuni:
--max-turns
: Massimo turni di conversazione (predefinito: 10)--model
: Modello da usare (es.,claude-sonnet-4-20250514
)--mcp-config
: Percorso alla configurazione MCP--allowed-tools
: Lista separata da virgole di strumenti consentiti--debug
: Abilita output debug
Metodi di integrazione alternativi
Mentre il comando /install-github-app
è l’approccio raccomandato, puoi anche:
- App GitHub Personalizzata: Per organizzazioni che necessitano di nomi utente brandizzati o flussi di autenticazione personalizzati. Crea la tua App GitHub con permessi richiesti (contents, issues, pull requests) e usa l’action actions/create-github-app-token per generare token nei tuoi flussi di lavoro.
- GitHub Actions Manuali: Configurazione diretta del flusso di lavoro per massima flessibilità
- Configurazione MCP: Caricamento dinamico di server Model Context Protocol
Vedi il repository Claude Code Action per documentazione dettagliata.
Personalizzazione del comportamento di Claude
Puoi configurare il comportamento di Claude in due modi:
- CLAUDE.md: Definisci standard di codifica, criteri di revisione e regole specifiche del progetto in un file
CLAUDE.md
alla radice del tuo repository. Claude seguirà queste linee guida quando crea PR e risponde alle richieste. Consulta la nostra documentazione Memory per maggiori dettagli. - Prompt personalizzati: Usa il parametro
prompt
nel file del flusso di lavoro per fornire istruzioni specifiche del flusso di lavoro. Questo ti permette di personalizzare il comportamento di Claude per diversi flussi di lavoro o compiti.
Claude seguirà queste linee guida quando crea PR e risponde alle richieste.