GitHub Actions: controlli rapidi quando il workflow fallisce

Quando un workflow si ferma, da dove partire

Un fallimento in GitHub Actions può dipendere da cause molto diverse: un runner non disponibile, un segreto mancante, un permesso insufficiente o un artefatto creato male. La chiave è isolare il punto esatto in cui la pipeline si interrompe.

Prima di cambiare codice o rilanciare il job più volte, conviene leggere con attenzione i log e verificare i passaggi fondamentali. In molti casi il problema non è nel repository, ma nell’ambiente di esecuzione o nella configurazione del workflow.

Controlli rapidi da fare subito

• Apri il log del job e individua il primo step in errore.
• Controlla se il runner è hosted o self-hosted e se risulta online.
• Verifica che il file YAML sia valido e che l’evento di trigger sia corretto.
• Controlla segreti, variabili d’ambiente e permessi del GITHUB_TOKEN.
• Esamina eventuali dipendenze fallite: installazione, build, test o deploy.

Runner, coda e disponibilità

Se il workflow resta in attesa o fallisce subito, il primo sospetto è il runner. Nei runner self-hosted verifica che il servizio sia attivo, che la macchina abbia spazio disco e che non sia bloccata da aggiornamenti o riavvii.

Nei runner ospitati da GitHub, invece, il problema può essere temporaneo. In quel caso vale la pena controllare se il job usa un’immagine specifica, una versione di sistema obsoleta o una configurazione troppo restrittiva.

Segnali tipici nel log

No runner matching the specified labels was found

The operation was canceled

Waiting for a runner to pick up this job...

Segreti e permessi

Molti workflow falliscono perché un segreto non è disponibile nel contesto giusto. Per esempio, un segreto definito a livello di ambiente potrebbe non essere accessibile da un branch non autorizzato, oppure un job di pull request potrebbe avere permessi ridotti.

Verifica anche i permessi del token automatico. Se il workflow deve creare release, scrivere su package registry o commentare su una issue, potrebbe servire una configurazione esplicita dei permessi.

Se un passaggio fallisce con errore di autenticazione, non dare per scontato che il segreto sia sbagliato: spesso il problema è il contesto in cui viene usato.

Cache, artefatti e dipendenze

Un altro punto critico è la cache. Una cache corrotta o non coerente può causare errori intermittenti, soprattutto su progetti con dipendenze pesanti. In questi casi conviene invalidare temporaneamente la cache e verificare se il workflow torna stabile.

Anche gli artefatti vanno controllati con attenzione: nome, percorso e retention possono cambiare facilmente tra uno step e l’altro. Se un job di deploy non trova il file previsto, spesso il problema è già avvenuto in build.

Trigger e filtri del workflow

Se il workflow non parte, il controllo va fatto sui trigger. Un errore comune è usare filtri troppo stretti su branch, tag o path. Basta una modifica nella struttura del repository perché il file YAML non intercetti più l’evento atteso.

• Verifica on: push, pull_request, workflow_dispatch o schedule.
• Controlla branch e tag inclusi o esclusi.
• Esamina i filtri su cartelle e file modificati.
• Conferma che il workflow sia presente nel branch giusto.

Una mini-checklist operativa

1. Leggi il primo errore reale nel log.
2. Controlla runner, etichette e disponibilità.
3. Verifica segreti, permessi e ambiente.
4. Isola cache e artefatti sospetti.
5. Rivedi trigger, branch e filtri.
6. Rilancia con una modifica minima per confermare la causa.

Quando serve andare oltre

Se il problema si ripete solo su un branch, su un tipo di evento o in un determinato runner, raccogli i dettagli e confronta le ultime modifiche al workflow. Spesso il guasto nasce da un cambiamento piccolo: un nome file, un path, un permesso o una versione di tool.

Per la documentazione ufficiale puoi consultare GitHub Actions Documentation.

Con un controllo ordinato di log, runner, segreti e trigger, la maggior parte dei workflow falliti si diagnostica in pochi minuti.