Come usare Claude Code GitHub Actions senza creare un'automazione aperta

Un commento di sei parole può avviare un processo con accesso al repository. Se il workflow può leggere issue, modificare file e pubblicare commit, la frase @claude sistemalo non è un brief. È un trigger senza un confine leggibile.

Claude Code GitHub Actions porta Claude dentro i workflow di GitHub. La documentazione ufficiale Anthropic descrive due usi principali: rispondere a una menzione in issue o pull request e partire automaticamente da un evento con un prompt configurato.

Prima di collegarlo a un repository, devi separare cinque decisioni: cosa lo avvia, chi ha l'autorità per farlo partire, quali tool può usare, quale output produce e chi lo rivede. Il file YAML arriva dopo.

Un commento può avviare un processo reale

La menzione sembra una conversazione, ma il suo effetto può essere quello di un job CI. Claude può analizzare il codice, preparare modifiche e pubblicare commit secondo workflow e permessi disponibili. Un evento programmato può partire senza una persona davanti allo schermo.

Tratta quindi il testo dell'issue come input non fidato. Potrebbe essere incompleto, ambiguo o scritto da qualcuno che non conosce il perimetro dell'Action. Il fatto che GitHub accetti il commento non dimostra che quella persona possa autorizzare ogni effetto possibile.

La prima domanda non è «quale prompt scrivo?». È «quale singolo job deve poter partire da questo evento?».

Scegli il job prima del trigger

Un job delimitato collega un oggetto GitHub a un risultato verificabile. Esempi:

• leggere un issue con un'etichetta precisa e produrre un'analisi nel log;

• confrontare una pull request con criteri dichiarati e proporre commenti;

• preparare una modifica su un branch dedicato e aprire una pull request;

• raccogliere commit e issue aperti in un report periodico.

«Migliorare il repository ogni notte» non è un job. Non definisce input, estensione delle modifiche o condizione di fine. Anche «risolvere gli issue» è troppo largo: alcuni richiedono una decisione di prodotto, altri toccano dati o servizi esterni.

Scegli un oggetto, un risultato e uno stop. Solo dopo decidi se l'avvio arriva da una menzione, da un'etichetta, dall'apertura di una pull request o da una cadenza.

Scrivi il contratto in cinque campi

Il contratto minimo sta in una tabella.

Scrivi anche le condizioni che producono un no-op: issue senza criteri di accettazione, repository non riconosciuto, secret mancante, file fuori perimetro o test non disponibile. Un workflow autonomo deve saper terminare senza fare una modifica.

La matrice di approvazione di un workflow AI aiuta a distinguere preparazione, proposta e azione. Portala nel repository come responsabilità, non come frase generica nel prompt.

Parti con un workflow in sola lettura

Il primo pilota non deve scrivere codice. Fagli leggere un issue e pochi file dichiarati, poi chiedi un report con quattro parti: interpretazione della richiesta, file probabilmente coinvolti, prove mancanti e motivi per cui non procederebbe.

Confronta l'output con un issue già risolto. Hai così un caso in cui conosci il percorso corretto e puoi misurare omissioni senza toccare il branch.

La scala di autonomia può crescere così:

1. leggi: analisi nel log, nessun commento e nessun commit;

2. proponi: commento o piano su un oggetto di prova;

3. modifica: branch e pull request, senza merge automatico.

Il merge resta una decisione separata finché non esistono prove specifiche, protezioni del branch e un'autorità esplicita. La comodità del trigger non deve accorciare il controllo finale.

Concedi permessi e tool per nome

GitHub definisce i permessi del token del workflow. Claude Code definisce anche quali tool può usare durante il run. Sono due perimetri sovrapposti: il primo limita l'identità del job, il secondo limita le azioni disponibili al modello.

La documentazione Anthropic chiarisce che un prompt eseguito in automation mode non ottiene per default shell o API GitHub. I tool vengono concessi negli argomenti o nelle impostazioni previste dal workflow. Questo è utile: parti da zero e aggiungi soltanto ciò che il job dimostra di richiedere.

Per un report su commit e issue, l'accesso in lettura può bastare. Non concedere contents: write perché immagini che forse servirà in futuro. Quando passi alla creazione di una pull request, apri una revisione del contratto e registra perché aumenta il perimetro.

Usa la pull request come confine di revisione

Una pull request rende visibili diff, test e discussione. È un confine migliore di un commit diretto sul branch principale, ma non approva da sola il contenuto.

Prima del merge controlla:

• che l'issue originale abbia criteri di accettazione leggibili;

• che i file modificati coincidano con il perimetro del job;

• che i test osservino il comportamento richiesto;

• che non siano comparsi secret, dati o file generati inattesi;

• che la descrizione della PR distingua prove eseguite e limiti rimasti.

Un check verde può significare soltanto che il comando è terminato con codice zero. Leggi il log e l'artefatto prodotto. L'audit trail di un workflow AI mostra quali eventi, input, decisioni e output servono per ricostruire un run.

Conserva secrets e istruzioni nel posto giusto

Chiavi API e token non entrano nel repository. La guida ufficiale richiede di conservarli nei GitHub Secrets e di richiamarli dal workflow. Evita anche di stamparli nei log o di passarli dentro il prompt.

Le istruzioni di progetto che valgono per ogni run possono stare nel CLAUDE.md del repository. Devono essere brevi: comandi di test, convenzioni, confini e criteri di revisione. Il testo dell'issue contiene invece i dettagli del singolo incarico.

Questa separazione riduce due errori. Le regole stabili non vengono riscritte in ogni commento. I dettagli temporanei non gonfiano le istruzioni caricate da ogni run.

Limita durata, turni e concorrenza

Ogni esecuzione consuma minuti GitHub Actions e uso del modello. Un job senza fine chiara può continuare a esplorare il repository senza aumentare la qualità del risultato.

Anthropic indica tre controlli pratici: limite ai turni, timeout del workflow e controllo della concorrenza. Aggiungi anche una dimensione massima dell'input quando l'evento può contenere molto testo. Se una pull request cambia centinaia di file, il comportamento corretto può essere produrre un blocco e richiedere una suddivisione.

Definisci cosa succede al fallimento. Un errore prima di qualsiasi scrittura può essere ritentato. Un commit pubblicato con esito incerto richiede prima una lettura dello stato remoto. Ripetere il job alla cieca può duplicare commenti, branch o commit.

Misura il pilota

Per i primi run registra fatti semplici: trigger ricevuto, identità valida, tool chiamati, file letti, output creato, durata e intervento umano. Non usare subito una metrica generica di produttività.

Il pilota regge se riduce un passaggio ripetuto senza moltiplicare revisioni e falsi allarmi. Se ogni issue richiede una spiegazione fuori dal template, migliora l'input. Se Claude chiede spesso un tool non concesso, verifica se il job è troppo largo prima di allargare i permessi.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi partire da un job di repository reale, costruire il contratto e provarlo prima in lettura. Il risultato utile non è vedere una pull request creata da sola. È sapere chi l'ha attivata, con quali poteri e quale prova serve prima del merge.