@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 sulla base di 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 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.mde i pattern di codice esistenti - Setup 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 sulla base di Claude Code. Visualizza repository →Setup
Setup 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 secret necessari.
- Devi essere un amministratore del repository per installare l’app GitHub e aggiungere secret
- L’app GitHub richiederà permessi di lettura e scrittura per Contents, Issues e Pull requests
- Questo metodo di quickstart è disponibile solo per gli utenti diretti dell’API Claude. Se stai usando AWS Bedrock o Google Vertex AI, consulta la sezione Using with AWS Bedrock & Google Vertex AI.
Setup manuale
Se il comando/install-github-app fallisce o preferisci il setup manuale, segui queste istruzioni di setup manuale:
-
Installa l’app GitHub di Claude nel tuo repository: https://github.com/apps/claude
L’app GitHub di Claude richiede i seguenti permessi 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 fare push dei cambiamenti)
- Aggiungi ANTHROPIC_API_KEY ai tuoi secret del repository (Scopri come usare i secret in GitHub Actions)
-
Copia il file del flusso di lavoro da examples/claude.yml nella cartella
.github/workflows/del tuo repository
Dopo aver completato il setup rapido o manuale, testa l’action taggando
@claude in un commento di issue o PR!Aggiornamento dalla Beta
Claude Code GitHub Actions v1.0 introduce cambiamenti che interrompono la compatibilità e richiedono l’aggiornamento dei tuoi file di flusso di lavoro per eseguire l’upgrade dalla versione beta a v1.0.
Cambiamenti essenziali
Tutti gli utenti beta devono apportare questi cambiamenti ai loro file di flusso di lavoro per eseguire l’upgrade:- Aggiorna la versione dell’action: Cambia
@betaa@v1 - Rimuovi la configurazione della modalità: Elimina
mode: "tag"omode: "agent"(ora rilevata automaticamente) - Aggiorna gli input del prompt: Sostituisci
direct_promptconprompt - Sposta le opzioni CLI: Converti
max_turns,model,custom_instructions, ecc. inclaude_args
Riferimento dei Cambiamenti che Interrompono la Compatibilità
| Input Beta Precedente | 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:L’action ora rileva automaticamente se eseguire in modalità interattiva (risponde alle menzioni
@claude) o in modalità automazione (viene eseguita immediatamente con un prompt) in base alla 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 di base
Utilizzo di comandi slash
Automazione personalizzata con prompt
Casi d’uso comuni
Nei commenti di issue o PR:Best practice
Configurazione CLAUDE.md
Crea un fileCLAUDE.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
Non committare mai le chiavi API direttamente nel tuo repository!
- 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 i permessi dell’action solo a quello che è necessario
- Rivedi i suggerimenti di Claude prima di fare il merge
${{ secrets.ANTHROPIC_API_KEY }}) piuttosto che hardcodare le chiavi API direttamente nei tuoi file di flusso di lavoro.
Ottimizzazione delle prestazioni
Usa template di issue per fornire contesto, mantieni il tuoCLAUDE.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 di GitHub Actions:- Claude Code viene eseguito su runner ospitati da GitHub, che consumano i tuoi minuti di GitHub Actions
- Consulta la documentazione sulla fatturazione di GitHub per i dettagli sui prezzi e i limiti di minuti
- 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
- Consulta la pagina dei prezzi di Claude per i tassi di token attuali
- Usa comandi specifici
@claudeper ridurre le chiamate API non necessarie - Configura
--max-turnsappropriato inclaude_argsper prevenire iterazioni eccessive - Imposta timeout a livello di flusso di lavoro per evitare job fuori controllo
- Considera l’uso dei controlli di concorrenza di GitHub per limitare le esecuzioni parallele
Esempi di configurazione
Claude Code Action v1 semplifica la configurazione con parametri unificati:- Interfaccia di prompt unificata - Usa
promptper tutte le istruzioni - Comandi slash - Prompt pre-costruiti come
/reviewo/fix - Passthrough CLI - Qualsiasi argomento CLI di Claude Code tramite
claude_args - Trigger flessibili - Funziona con qualsiasi evento GitHub
Quando rispondi ai commenti di issue o PR, Claude risponde automaticamente alle menzioni @claude. Per altri eventi, usa il parametro
prompt per fornire istruzioni.Utilizzo con AWS Bedrock e Google Vertex AI
Per ambienti enterprise, puoi usare 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 i permessi richiesti
- Un’app GitHub (consigliato) o usa il GITHUB_TOKEN predefinito
Per AWS Bedrock:
- Un account AWS con Amazon Bedrock abilitato
- GitHub OIDC Identity Provider configurato in AWS
- Un ruolo IAM con permessi Bedrock
- Un’app GitHub (consigliato) o usa il GITHUB_TOKEN predefinito
1
Crea un'app GitHub personalizzata (Consigliato per provider di terze parti)
Per il miglior controllo e sicurezza quando usi provider di terze parti come Vertex AI o Bedrock, ti consigliamo di creare la tua app GitHub:Alternativa per Claude API o se non vuoi configurare la tua app Github: Usa l’app ufficiale di Anthropic:
- Vai a https://github.com/settings/apps/new
- Compila le informazioni di base:
- Nome dell’app GitHub: Scegli un nome univoco (ad es., “YourOrg Claude Assistant”)
- URL della homepage: Il sito web della tua organizzazione o l’URL del repository
- Configura le impostazioni dell’app:
- Webhook: Deseleziona “Active” (non necessario per questa integrazione)
- Imposta i permessi richiesti:
- Permessi del repository:
- Contents: Lettura e Scrittura
- Issues: Lettura e Scrittura
- Pull requests: Lettura e Scrittura
- Permessi del repository:
- Fai clic su “Create GitHub App”
- Dopo la creazione, fai clic su “Generate a private key” e salva il file
.pemscaricato - Annota il tuo App ID dalla pagina delle impostazioni dell’app
- Installa l’app nel tuo repository:
- Dalla pagina delle impostazioni della tua app, fai clic su “Install App” nella barra laterale sinistra
- Seleziona il tuo account o organizzazione
- Scegli “Only select repositories” e seleziona il repository specifico
- Fai clic su “Install”
- Aggiungi la chiave privata come secret al tuo repository:
- Vai a Settings → Secrets and variables → Actions del tuo repository
- Crea un nuovo secret denominato
APP_PRIVATE_KEYcon il contenuto del file.pem
- Aggiungi l’App ID come secret:
- Crea un nuovo secret denominato
APP_IDcon l’ID della tua app GitHub
Questa app verrà usata con l’action actions/create-github-app-token per generare token di autenticazione nei tuoi flussi di lavoro.
- Installa da: https://github.com/apps/claude
- Nessuna configurazione aggiuntiva necessaria per l’autenticazione
2
Configura l'autenticazione del provider cloud
Scegli il tuo provider cloud e configura l’autenticazione sicura:
AWS Bedrock
AWS Bedrock
Configura AWS per consentire a GitHub Actions di autenticarsi in modo sicuro senza archiviare le credenziali.Consulta la documentazione di AWS per le istruzioni dettagliate di setup di OIDC.
Nota sulla sicurezza: Usa configurazioni specifiche del repository e concedi solo i permessi minimi richiesti.Setup richiesto:
-
Abilita Amazon Bedrock:
- Richiedi accesso ai modelli Claude in Amazon Bedrock
- Per i modelli multi-region, richiedi accesso in tutte le regioni richieste
-
Configura il provider di identità GitHub OIDC:
- URL del provider:
https://token.actions.githubusercontent.com - Audience:
sts.amazonaws.com
- URL del provider:
-
Crea il ruolo IAM per GitHub Actions:
- Tipo di entità attendibile: Web identity
- Provider di identità:
token.actions.githubusercontent.com - Permessi: policy
AmazonBedrockFullAccess - Configura la policy di trust per il tuo repository specifico
- AWS_ROLE_TO_ASSUME: L’ARN del ruolo IAM che hai creato
OIDC è più sicuro rispetto all’uso di chiavi di accesso AWS statiche perché le credenziali sono temporanee e ruotate automaticamente.
Google Vertex AI
Google Vertex AI
Configura Google Cloud per consentire a GitHub Actions di autenticarsi in modo sicuro senza archiviare le credenziali.Per le istruzioni di setup dettagliate, consulta la documentazione di Google Cloud Workload Identity Federation.
Nota sulla sicurezza: Usa configurazioni specifiche del repository e concedi solo i permessi minimi richiesti.Setup richiesto:
-
Abilita le API nel tuo progetto Google Cloud:
- IAM Credentials API
- Security Token Service (STS) API
- Vertex AI API
-
Crea risorse Workload Identity Federation:
- Crea un Workload Identity Pool
- Aggiungi un provider OIDC GitHub con:
- Issuer:
https://token.actions.githubusercontent.com - Mappature di attributi per repository e proprietario
- Raccomandazione sulla sicurezza: Usa condizioni di attributi specifiche del repository
- Issuer:
-
Crea un account di servizio:
- Concedi solo il ruolo
Vertex AI User - Raccomandazione sulla sicurezza: Crea un account di servizio dedicato per repository
- Concedi solo il ruolo
-
Configura i binding IAM:
- Consenti al Workload Identity Pool di impersonare l’account di servizio
- Raccomandazione sulla sicurezza: Usa set di principal specifici del repository
- GCP_WORKLOAD_IDENTITY_PROVIDER: Il nome completo della risorsa del provider
- GCP_SERVICE_ACCOUNT: L’indirizzo email dell’account di servizio
Workload Identity Federation elimina la necessità di chiavi di account di servizio scaricabili, migliorando la sicurezza.
3
Aggiungi i secret richiesti
Aggiungi i seguenti secret al tuo repository (Settings → Secrets and variables → Actions):
Per Claude API (Diretto):
-
Per l’autenticazione API:
ANTHROPIC_API_KEY: La tua chiave API Claude da console.anthropic.com
-
Per l’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 l’autenticazione GCP:
GCP_WORKLOAD_IDENTITY_PROVIDERGCP_SERVICE_ACCOUNT
-
Per l’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 l’autenticazione AWS:
AWS_ROLE_TO_ASSUME
-
Per l’app GitHub (se usi la tua app):
APP_ID: L’ID della tua app GitHubAPP_PRIVATE_KEY: Il contenuto della chiave privata (.pem)
4
Crea file di flusso di lavoro
Crea file di flusso di lavoro 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:
Flusso di lavoro AWS Bedrock
Flusso di lavoro AWS Bedrock
Prerequisiti:
- Accesso ad AWS Bedrock abilitato con permessi per modelli Claude
- GitHub configurato come provider di identità OIDC in AWS
- Ruolo IAM con permessi Bedrock che si fida di GitHub Actions
| Nome del secret | Descrizione |
|---|---|
AWS_ROLE_TO_ASSUME | ARN del ruolo IAM per l’accesso a Bedrock |
APP_ID | L’ID della tua app GitHub (dalle impostazioni dell’app) |
APP_PRIVATE_KEY | La chiave privata che hai generato per la tua app GitHub |
Il formato dell’ID del modello per Bedrock include il prefisso della regione (ad es.,
us.anthropic.claude...) e il suffisso della versione.Flusso di lavoro Google Vertex AI
Flusso di lavoro Google Vertex AI
Prerequisiti:
- Vertex AI API abilitata nel tuo progetto GCP
- Workload Identity Federation configurata per GitHub
- Account di servizio con permessi Vertex AI
| Nome del secret | Descrizione |
|---|---|
GCP_WORKLOAD_IDENTITY_PROVIDER | Nome della risorsa del provider di identità del carico di lavoro |
GCP_SERVICE_ACCOUNT | Email dell’account di servizio con accesso a Vertex AI |
APP_ID | L’ID della tua app GitHub (dalle impostazioni dell’app) |
APP_PRIVATE_KEY | La chiave privata che hai generato per la tua app GitHub |
L’ID del progetto viene recuperato automaticamente dal passaggio di autenticazione di Google Cloud, quindi non è necessario codificarlo.
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 secret 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 un’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 secret siano denominati correttamente nei flussi di lavoro.Configurazione avanzata
Parametri dell’action
Claude Code Action v1 utilizza 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 Claude | Sì** |
github_token | Token GitHub per l’accesso API | No |
trigger_phrase | Frase di trigger personalizzata (predefinito: “@claude”) | No |
use_bedrock | Usa AWS Bedrock invece dell’API Claude | No |
use_vertex | Usa Google Vertex AI invece dell’API Claude | No |
**Richiesto per l’API Claude diretta, non per Bedrock/Vertex
Utilizzo di claude_args
Il parametroclaude_args accetta qualsiasi argomento CLI di Claude Code:
--max-turns: Numero massimo di turni di conversazione (predefinito: 10)--model: Modello da usare (ad es.,claude-sonnet-4-5-20250929)--mcp-config: Percorso della configurazione MCP--allowed-tools: Elenco separato da virgole degli strumenti consentiti--debug: Abilita l’output di debug
Metodi di integrazione alternativi
Mentre il comando/install-github-app è l’approccio consigliato, puoi anche:
- App GitHub personalizzata: Per le organizzazioni che hanno bisogno di nomi utente personalizzati o flussi di autenticazione personalizzati. Crea la tua app GitHub con i 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 manuale: Configurazione diretta del flusso di lavoro per la massima flessibilità
- Configurazione MCP: Caricamento dinamico dei server Model Context Protocol
Personalizzazione del comportamento di Claude
Puoi configurare il comportamento di Claude in due modi:- CLAUDE.md: Definisci gli standard di codifica, i criteri di revisione e le regole specifiche del progetto in un file
CLAUDE.mdnella radice del tuo repository. Claude seguirà queste linee guida quando crea PR e risponde alle richieste. Consulta la nostra documentazione sulla memoria per ulteriori dettagli. - Prompt personalizzati: Usa il parametro
promptnel 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.