GitHub Actions
Integra Claude Code con i tuoi flussi di lavoro GitHub per la revisione automatica del codice, la gestione delle PR e lo smistamento dei problemi.
Claude Code GitHub Actions porta l’automazione basata sull’IA nel 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.
Claude Code GitHub Actions è attualmente in versione beta. Le funzionalità potrebbero evolversi mentre perfezioniamo l’esperienza.
Claude Code GitHub Actions è costruito sulla base del Claude Code SDK, che consente l’integrazione programmatica di Claude Code nelle tue applicazioni. Puoi utilizzare l’SDK per creare flussi di lavoro di automazione personalizzati oltre GitHub Actions.
Perché utilizzare Claude Code GitHub Actions?
- Creazione istantanea di PR: Descrivi ciò di cui hai bisogno e Claude crea una PR completa con tutte le modifiche necessarie
- Implementazione automatica del codice: Trasforma i problemi in codice funzionante con un singolo comando
- Rispetta 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 potenti GitHub Actions che trasformano 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 utilizzarla per costruire qualsiasi flusso di lavoro personalizzato basato su Claude Code.
Claude Code Action (Base)
La base per costruire flussi di lavoro GitHub personalizzati con Claude. Questo framework estensibile ti dà pieno accesso alle capacità di Claude per creare automazioni su misura.
Avvio rapido
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 segreti richiesti.
- Devi essere un amministratore del repository per installare l’app GitHub e aggiungere i segreti
- Questo metodo di avvio rapido è disponibile solo per gli utenti diretti dell’API Anthropic. Se stai utilizzando AWS Bedrock o Google Vertex AI, consulta la sezione Utilizzo con AWS Bedrock e Google Vertex AI.
Se lo script di configurazione fallisce
Se il comando /install-github-app
fallisce o preferisci la configurazione manuale, segui queste istruzioni per la 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 utilizzare i segreti in GitHub Actions)
- Copia il file del workflow da examples/claude.yml nella directory
.github/workflows/
del tuo repository
Testa l'action
Dopo aver completato la configurazione rapida o manuale, testa l’action taggando @claude
in un commento di un’issue o PR!
Esempi di casi d’uso
Claude Code GitHub Actions può aiutarti con una varietà di attività. Per esempi completi e funzionanti, consulta la directory degli esempi.
Trasforma le issue in PR
Claude analizzerà l’issue, scriverà il codice e creerà una PR per la revisione.
Ottieni aiuto per l’implementazione
Claude analizzerà il tuo codice e fornirà indicazioni specifiche per l’implementazione.
Correggi i bug rapidamente
Claude individuerà il bug, implementerà una correzione e creerà una PR.
Best practice
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
⚠️ IMPORTANTE: Non committare mai le chiavi API direttamente nel tuo repository!
Utilizza sempre i Segreti GitHub per le chiavi API:
- Aggiungi la tua chiave API come segreto del repository chiamato
ANTHROPIC_API_KEY
- Fai riferimento ad essa nei workflow:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
- Limita i permessi dell’action solo a ciò che è necessario
- Rivedi i suggerimenti di Claude prima di unirli
Utilizza sempre i Segreti GitHub (ad esempio, ${{ secrets.ANTHROPIC_API_KEY }}
) invece di codificare direttamente le chiavi API nei file del workflow.
Ottimizzazione delle prestazioni
Utilizza modelli di issue per fornire contesto, mantieni il tuo CLAUDE.md
conciso e mirato, e configura timeout appropriati per i tuoi workflow.
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
- Consulta la documentazione di fatturazione di GitHub per i prezzi dettagliati e i limiti di minuti
Costi API:
- Ogni interazione con 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 alle dimensioni della codebase
- Consulta la pagina dei prezzi di Claude per le tariffe correnti dei token
Suggerimenti per l’ottimizzazione dei costi:
- Utilizza comandi
@claude
specifici per ridurre le chiamate API non necessarie - Configura limiti
max_turns
appropriati per prevenire iterazioni eccessive - Imposta
timeout_minutes
ragionevoli per evitare workflow fuori controllo - Considera l’utilizzo dei controlli di concorrenza di GitHub per limitare le esecuzioni parallele
Esempi di configurazione
Per configurazioni di workflow pronte all’uso per diversi casi d’uso, tra cui:
- Configurazione di base del workflow per commenti su issue e PR
- Revisioni di codice automatizzate sulle pull request
- Implementazioni personalizzate per esigenze specifiche
Visita la directory degli esempi nel repository Claude Code Action.
Il repository degli esempi include workflow completi e testati che puoi copiare direttamente nella tua directory .github/workflows/
.
Utilizzo con AWS 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:
- Un progetto Google Cloud con Vertex AI abilitato
- Workload Identity Federation configurato per GitHub Actions
- Un account di servizio con le autorizzazioni richieste
- Un’app GitHub (consigliata) o utilizzare 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 autorizzazioni Bedrock
- Un’app GitHub (consigliata) o utilizzare il GITHUB_TOKEN predefinito
Crea un'app GitHub personalizzata (Consigliato per provider di terze parti)
Per un migliore controllo e sicurezza quando si utilizzano provider di terze parti come Vertex AI o Bedrock, consigliamo 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 univoco (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 le autorizzazioni richieste:
- Autorizzazioni repository:
- Contents: Read & Write
- Issues: Read & Write
- Pull requests: Read & Write
- Autorizzazioni repository:
- Clicca “Create GitHub App”
- Dopo la creazione, clicca “Generate a private key” e salva il file
.pem
scaricato - Prendi nota del 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 alle 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à utilizzata con l’action actions/create-github-app-token per generare token di autenticazione nei tuoi workflow.
Alternativa per l’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 i segreti richiesti
Aggiungi i seguenti segreti al tuo repository (Impostazioni → Secrets and variables → Actions):
Per API Anthropic (Diretta):
-
Per l’autenticazione API:
ANTHROPIC_API_KEY
: La tua chiave API Anthropic da console.anthropic.com
-
Per l’app GitHub (se utilizzi 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 l’autenticazione GCP:
GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT
-
Per l’app GitHub (se utilizzi la tua app):
APP_ID
: L’ID della tua app GitHubAPP_PRIVATE_KEY
: Il contenuto della chiave privata (.pem)
Per AWS Bedrock
-
Per l’autenticazione AWS:
AWS_ROLE_TO_ASSUME
-
Per l’app GitHub (se utilizzi la tua app):
APP_ID
: L’ID della tua app GitHubAPP_PRIVATE_KEY
: Il contenuto della chiave privata (.pem)
Crea file di workflow
Crea file di workflow GitHub Actions che si integrano con il tuo provider cloud. Gli esempi seguenti 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 workflow siano abilitati, assicurati che la chiave API sia impostata nei segreti 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 un’app personalizzata (non l’utente Actions), controlla che i trigger del workflow 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 segreti siano denominati correttamente nei workflow.
Configurazione avanzata
Parametri dell’action
Claude Code Action supporta questi parametri chiave:
Parametro | Descrizione | Richiesto |
---|---|---|
prompt | Il prompt da inviare a Claude | Sì* |
prompt_file | Percorso del file contenente il prompt | Sì* |
anthropic_api_key | Chiave API Anthropic | Sì** |
max_turns | Numero massimo di turni di conversazione | No |
timeout_minutes | Timeout di esecuzione | No |
*È richiesto prompt
o prompt_file
**Richiesto per l’API Anthropic diretta, non per Bedrock/Vertex
Metodi di integrazione alternativi
Mentre il comando /install-github-app
è l’approccio consigliato, puoi anche:
- App GitHub personalizzata: Per 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 workflow.
- GitHub Actions manuali: Configurazione diretta del workflow per la massima flessibilità
- Configurazione MCP: Caricamento dinamico dei server Model Context Protocol
Consulta il repository Claude Code Action per la 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
nella radice del tuo repository. Claude seguirà queste linee guida quando crea PR e risponde alle richieste. Consulta la nostra documentazione sulla Memoria per maggiori dettagli. - Prompt personalizzati: Utilizza il parametro
prompt
nel file del workflow per fornire istruzioni specifiche per il workflow. Questo ti permette di personalizzare il comportamento di Claude per diversi workflow o attività.
Claude seguirà queste linee guida quando crea PR e risponde alle richieste.