Il lockfile di GitHub Actions fissa il codice eseguito, ma non l’intera CI

Ci si può fidare di GitHub Actions quando un workflow richiama un’action tramite un tag come @v3? Il lockfile specifica quale commit dell’action verrà eseguito, anche se in seguito il tag viene spostato. Il team può esaminare gli aggiornamenti delle dipendenze nei diff e mantenere un elenco verificabile delle actions usate dalla CI. Il limite pratico è che il lockfile copre le actions richiamate nei passaggi, mentre un reusable workflow richiamato a livello di job va fissato separatamente. Il meccanismo descritto è disponibile in GitHub Enterprise Cloud.

Che cosa fissa esattamente il lockfile?

I riferimenti a branch e tag sono comodi, ma la versione a cui puntano può cambiare. Una voce come uses: octo-org/deploy-action@v3 indica il nome del tag; GitHub risolve il riferimento in un commit quando viene eseguito il workflow. Se il proprietario del progetto sposta il tag, la successiva esecuzione può ricevere codice diverso senza una dipendenza fissata.

Secondo la documentazione di GitHub sui lockfile, il file .github/workflows/actions.lock memorizza i riferimenti alle dipendenze e i relativi commit SHA, incluse le dipendenze transitive, cioè le actions usate da altre actions. Il file viene creato dall’estensione di GitHub CLI gh actions-lock e non va modificato manualmente.

Il generatore può anche rendere più precisi i riferimenti uses nei file workflow: per esempio, può sostituire un tag mobile con un riferimento più specifico, conservando il commit a cui puntava al momento della creazione del lockfile. Perciò, durante l’adozione, occorre esaminare l’intero diff — le modifiche ai workflow e al lockfile — e verificare che la versione fissata sia quella che il team intende eseguire.

In seguito, l’aggiornamento di una dipendenza diventa una modifica visibile nel repository: il team può esaminare la variazione del commit, discuterla e approvarla tramite il normale processo di review. Il lockfile aiuta a verificare il codice delle actions e a mantenere coerenti le dipendenze; da solo, però, non certifica la sicurezza del codice scelto.

Dove termina l’ambito del lockfile?

Una chiamata a un reusable workflow in jobs.<job_id>.uses non viene fissata dal lockfile del repository che la richiama. Le dipendenze del reusable workflow appartengono al repository in cui è definito. Per fissare la chiamata stessa, specificate il commit SHA completo; per fissarne le actions nel repository di origine, serve un lockfile dedicato.

Il lockfile controlla il codice delle actions, ma non gli altri input di compilazione, come i parametri passati a un’action, i segreti o l’immagine del runner. Risponde a una domanda precisa: quale commit del codice dell’action verrà eseguito? Questi altri elementi richiedono regole di gestione proprie.

Esiste anche un caso particolare: un’action locale richiamata tramite un percorso come uses: ./. Secondo le istruzioni di GitHub, l’estensione gh actions-lock non fissa né analizza il percorso di un’action locale. Se quell’action usa altre actions, le dipendenze vanno gestite separatamente; la documentazione descrive un’opzione per migrare i riferimenti alle actions locali nel formato $.

Di conseguenza, una voce nel lockfile può coprire una parte della catena, ma non sostituisce il controllo di tutti i suoi elementi. Per un reusable workflow esterno, verificate il riferimento fissato e lo stato del repository di origine; per le actions locali, controllate come vengono gestite le relative dipendenze.

Come introdurre i controlli senza bloccare all’improvviso la CI?

GitHub consiglia di iniziare con un progetto pilota su repository e workflow selezionati. La policy Require lockfile blocca l’esecuzione dei workflow interessati se manca un lockfile valido, anche quando il workflow non contiene dipendenze uses:. La modalità Evaluate per le policy è disponibile solo in GitHub Enterprise Cloud. Preparate quindi l’ambito e gli aggiornamenti automatici prima di rendere obbligatoria la regola.

1. Verificate i riferimenti iniziali. Prima di creare il lockfile, assicuratevi che le actions puntino alle versioni che il team intende davvero fissare. Il generatore blocca il commit risolto a partire dal riferimento corrente.
2. Create ed esaminate il lockfile. Installate l’estensione gh-actions-lock, eseguite gh actions-lock dalla radice del repository ed esaminate il diff completo, compresi i riferimenti uses riscritti.
3. Impostate aggiornamenti e verifiche. Dependabot può aggiornare le voci pertinenti per i workflow già configurati. Nella CI delle pull request potete impostare un job di verifica con gh actions-lock --verify, così da individuare un lockfile obsoleto prima della compilazione principale.
4. Assegnate i revisori. Aggiungete .github/workflows/actions.lock a CODEOWNERS e richiedete la verifica delle modifiche da parte dei responsabili della sicurezza della build.
5. Avviate un progetto pilota della policy. Cominciate con repository e workflow già configurati. In modalità Evaluate, analizzate i risultati; prima di passare alla modalità Active, verificate che tutti i workflow interessati siano pronti e che i lockfile siano aggiornati.

Require lockfile e la policy separata Require actions to be pinned to a full-length commit SHA sono regole diverse; GitHub indica che possono rimanere attive contemporaneamente. Anche la verifica nella CI e la policy obbligatoria svolgono ruoli distinti: la prima individua un file obsoleto mentre si lavora a una pull request, la seconda blocca l’esecuzione dei workflow che non rispettano il requisito.

Esempio: aggiornare un’action di deployment

Supponiamo che un workflow pubblichi un’applicazione tramite octo-org/deploy-action@v3. Per prima cosa, il team verifica a quale versione risolve il riferimento; poi esegue gh actions-lock ed esamina il diff del workflow insieme alla voce del commit nel lockfile. Quando l’action viene aggiornata, chi revisiona vede le modifiche ai riferimenti e al commit fissato: così può valutare un aggiornamento specifico invece di fare affidamento sul fatto che un tag mobile punti sempre allo stesso codice.

Se il deployment è eseguito da un reusable workflow in un altro repository, il lockfile locale non copre le sue dipendenze. Fissate il riferimento al reusable workflow tramite SHA completo e verificate che il repository di origine gestisca le proprie dipendenze dalle actions. Nelle organizzazioni di grandi dimensioni, questo trasforma regole frammentarie in un processo verificabile, mantenendo separato il controllo di parametri, segreti e runner.

Il lockfile è un utile livello di controllo per il codice delle actions: rende visibili versioni e aggiornamenti, comprese le dipendenze transitive. Per una copertura affidabile, verificate anche i reusable workflow e le actions locali, automatizzate gli aggiornamenti e introducete la policy obbligatoria solo dopo un progetto pilota.