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.

Visualizza repository →

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:

  1. Installa l’app GitHub Claude nel tuo repository: https://github.com/apps/claude
  2. Aggiungi ANTHROPIC_API_KEY ai segreti del tuo repository (Scopri come usare i segreti in GitHub Actions)
  3. 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:

  1. Aggiorna la versione dell’action: Cambia @beta in @v1
  2. Rimuovi la configurazione della modalità: Elimina mode: "tag" o mode: "agent" (ora rilevato 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

Riferimento delle Modifiche che Rompono la Compatibilità

Vecchio Input BetaNuovo Input v1.0
mode(Rimosso - rilevato automaticamente)
direct_promptprompt
override_promptprompt con variabili GitHub
custom_instructionsclaude_args: --system-prompt
max_turnsclaude_args: --max-turns
modelclaude_args: --model
allowed_toolsclaude_args: --allowedTools
disallowed_toolsclaude_args: --disallowedTools
claude_envsettings formato JSON

Esempio Prima e Dopo

Versione beta:

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Rivedi questa PR per problemi di sicurezza"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Segui i nostri standard di codifica"
    max_turns: "10"
    model: "claude-3-5-sonnet-20241022"

Versione GA (v1.0):

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Rivedi questa PR per problemi di sicurezza"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --system-prompt "Segui i nostri standard di codifica"
      --max-turns 10
      --model claude-sonnet-4-20250514

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

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 }}
          # Risponde alle menzioni @claude nei commenti

Uso dei comandi slash

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 }}
          prompt: "/review"
          claude_args: "--max-turns 5"

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: "Genera un riassunto dei commit di ieri e delle issue aperte"
          claude_args: "--model claude-opus-4-1-20250805"

Casi d’uso comuni

Nei commenti di issue o PR:

@claude implementa questa funzionalità basandoti sulla descrizione dell'issue
@claude come dovrei implementare l'autenticazione utente per questo endpoint?
@claude correggi il TypeError nel componente dashboard utente

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

Non committare mai le chiavi API direttamente nel tuo repository!

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:

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 in claude_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:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Le tue istruzioni qui" # Opzionale
    claude_args: "--max-turns 5" # Argomenti CLI opzionali

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:

  1. Un Progetto Google Cloud con Vertex AI abilitato
  2. Workload Identity Federation configurato per GitHub Actions
  3. Un account di servizio con i permessi richiesti
  4. Un’App GitHub (raccomandato) o usa il GITHUB_TOKEN predefinito

Per AWS Bedrock:

  1. Un account AWS con Amazon Bedrock abilitato
  2. Provider di Identità OIDC GitHub configurato in AWS
  3. Un ruolo IAM con permessi Bedrock
  4. Un’App GitHub (raccomandato) o usa il GITHUB_TOKEN predefinito
1

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:

  1. Vai su https://github.com/settings/apps/new
  2. 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
  3. Configura le impostazioni dell’app:
    • Webhooks: Deseleziona “Active” (non necessario per questa integrazione)
  4. Imposta i permessi richiesti:
    • Permessi repository:
      • Contents: Read & Write
      • Issues: Read & Write
      • Pull requests: Read & Write
  5. Clicca “Create GitHub App”
  6. Dopo la creazione, clicca “Generate a private key” e salva il file .pem scaricato
  7. Annota il tuo App ID dalla pagina delle impostazioni dell’app
  8. 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”
  9. 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
  10. 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:

  1. Installa da: https://github.com/apps/claude
  2. Nessuna configurazione aggiuntiva necessaria per l’autenticazione
2

Configura l'autenticazione del provider cloud

Scegli il tuo provider cloud e configura l’autenticazione sicura:

3

Aggiungi Segreti Richiesti

Aggiungi i seguenti segreti al tuo repository (Settings → Secrets and variables → Actions):

Per API Anthropic (Diretta):

  1. Per Autenticazione API:

  2. Per App GitHub (se usi la tua app):

    • APP_ID: L’ID della tua App GitHub
    • APP_PRIVATE_KEY: Il contenuto della chiave privata (.pem)

Per Google Cloud Vertex AI

  1. Per Autenticazione GCP:

    • GCP_WORKLOAD_IDENTITY_PROVIDER
    • GCP_SERVICE_ACCOUNT
  2. Per App GitHub (se usi la tua app):

    • APP_ID: L’ID della tua App GitHub
    • APP_PRIVATE_KEY: Il contenuto della chiave privata (.pem)

Per AWS Bedrock

  1. Per Autenticazione AWS:

    • AWS_ROLE_TO_ASSUME
  2. Per App GitHub (se usi la tua app):

    • APP_ID: L’ID della tua App GitHub
    • APP_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 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:

ParametroDescrizioneRichiesto
promptIstruzioni per Claude (testo o comando slash)No*
claude_argsArgomenti CLI passati a Claude CodeNo
anthropic_api_keyChiave API AnthropicSì**
github_tokenToken GitHub per accesso APINo
trigger_phraseFrase trigger personalizzata (predefinito: “@claude”)No
use_bedrockUsa AWS Bedrock invece dell’API AnthropicNo
use_vertexUsa Google Vertex AI invece dell’API AnthropicNo

*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:

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

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:

  1. 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.
  2. 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.