GitHub Actions cache-mode: verificare i permessi di cache dietro una CI verde
Se la CI termina con successo (verde) ma all'esecuzione successiva scarica di nuovo le dipendenze, è facile pensare subito a correggere la chiave della cache. Ora, però, è necessario verificare anche se il salvataggio sia stato ignorato a causa dei permessi. Il semplice fatto che un workflow sia andato a buon fine non garantisce che la cache sia stata effettivamente creata.
Il 10 settembre 2026 GitHub ha annunciato la disponibilità generale di cache-mode. Su tutti i piani di github.com è ora possibile definire l'accesso alla cache a livello di workflow o di singolo job. Facendo un passo avanti rispetto al precedente articolo incentrato sui valori predefiniti di sola lettura, questa volta ci concentriamo sulle configurazioni esplicite e sui metodi di verifica.
Funzionalità confermata: quattro combinazioni di ripristino e salvataggio
read consente solo il ripristino, mentre write consente sia il ripristino sia il salvataggio. write-only consente solo il salvataggio e none blocca entrambi. Il primo controllo da fare è non fraintendere il nome write considerandolo come dedicato al solo salvataggio.
I valori dichiarati a livello di job hanno la priorità sulle impostazioni dell'intero workflow. Al contrario, nelle chiamate a un reusable workflow non è possibile ottenere un livello di accesso superiore a quello concesso dal chiamante. Non giudicare i permessi effettivi dell'intera esecuzione leggendo solo le dichiarazioni di un singolo file.
Un'esecuzione verde non è una prova di salvataggio
La documentazione ufficiale spiega che le operazioni di cache non consentite lasciano un log informativo e consentono all'esecuzione di proseguire. Un ripristino bloccato viene trattato come un cache miss, mentre un salvataggio bloccato non viene eseguito. Il punto chiave per l'osservabilità è che il workflow in sé non fallisce.
Pertanto, a livello operativo è utile separare l'esito dell'esecuzione dal risultato della cache. Verifica in una singola esecuzione quale evento l'ha avviata, quale modalità è stata applicata, se il ripristino è avvenuto e se il salvataggio è stato ignorato. Questa è una procedura operativa consigliata basata sulla descrizione ufficiale delle funzionalità, non una nuova interfaccia di dashboard fornita automaticamente.
Creare una piccola matrice dei permessi prima dell'applicazione
Esamina i workflow reali del repository e individua i job che producono cache e quelli che la consumano. Non è necessario raggruppare sotto gli stessi permessi il job che prepara le dipendenze su un branch fidato, quello che testa modifiche esterne e quello che valida gli artefatti di rilascio.
Scrivi due frasi per ciascun job: questo job deve leggere la cache esistente? È consentito che il risultato di questo job venga conservato affinché l'esecuzione successiva lo legga? Se entrambi non sono necessari, puoi riconsiderare l'abitudine di associare la cache a ogni costo. Tuttavia, la configurazione effettiva deve essere determinata in base ai confini di attendibilità e alla struttura di compilazione del repository.
Esperimento minimo: job consumatore in sola lettura
Ad esempio, in un workflow di test dichiara cache-mode: read al livello superiore e assicurati che non vi siano override nei singoli job. Confronta se i risultati dei test con l'uso della cache sono identici a quelli ottenuti senza cache. Poiché la cache deve essere uno strumento ausiliario per ridurre i tempi di esecuzione, se l'assenza di cache altera la correttezza del test, è necessario prima verificare le assunzioni di compilazione.
Il criterio di superamento di questo esperimento non è una singola riga di successo nella CI. Devi essere in grado di spiegare il tentativo di ripristino e l'omissione del salvataggio, potendo convalidare nuovamente l'esecuzione successiva con gli stessi input. Registrando i commit prima e dopo l'esperimento, i trigger, le impostazioni effettive e la posizione dei log, sarà facile anche per i colleghi riprodurre la valutazione.
Per i reusable workflow, analizzare l'intero percorso di chiamata
Anche se hai impostato valori predefiniti sicuri in un workflow condiviso, devi esaminare insieme il contesto del chiamante e le impostazioni dei singoli job. Il fatto che diversi repository richiamino lo stesso file non significa che vengano eseguiti con gli stessi permessi.
Durante la revisione, parti dal chiamante, segui la dichiarazione di cache del job e infine l'ordine del workflow richiamato. Se i permessi previsti differiscono dai log effettivi, individua l'origine della configurazione prima di rendere la chiave ancora più complessa. Questo è un suggerimento per ridurre i tempi di diagnosi nelle organizzazioni con un alto riutilizzo di workflow e non implica metriche misurate di miglioramento delle prestazioni.
Eccezioni a cui prestare attenzione e ordine di applicazione
Se specifichi write o write-only per eventi a bassa attendibilità come pull_request_target, potresti sovrascrivere la restrizione predefinita di sola lettura e aumentare il rischio di avvelenamento della cache. In questo caso, GitHub aggiunge un'annotazione di avviso. È bene evitare di rispondere a questi avvisi aumentando i permessi di scrittura solo per farli sparire.
Al contrario, anche la scelta di bloccare completamente la cache comporta un costo. I tempi di download e di compilazione potrebbero aumentare, quindi confronta direttamente il tempo di esecuzione su un job rappresentativo prima di estendere l'ambito. Invece di promettere effetti sulle prestazioni basati su stime, è meglio che il team decida insieme le restrizioni necessarie per la sicurezza e i rallentamenti accettabili.
Domande che il team dovrebbe porsi adesso
Il compito di oggi non è aggiungere in blocco la nuova configurazione a tutti i repository. Consiste nell'individuare i produttori e i consumatori di cache in un singolo workflow critico, definire i permessi e verificare le prove di ripristino e salvataggio in un'unica esecuzione. Se si tratta di un job di deployment, mantieni le modifiche ridotte affinché il responsabile possa leggere i log e verificare che corrispondano alle aspettative.
La domanda che potrebbe sorgere nella pratica è: perché la CI ha avuto successo se la fase di salvataggio è stata ignorata? Questo articolo spiega tale confusione basandosi sul comportamento ufficiale e non fa riferimento a sondaggi della community o tassi di errore universali. Quando introduci una nuova funzionalità, verificare separatamente i risultati prestazionali e quelli relativi ai permessi ti consentirà di classificare con maggiore precisione il prossimo problema di cache.