Gestione dei segreti di GitHub Actions: proteggere chiavi API e password nei workflow

By Mirko Peters · 2026-10-26

Scopri come proteggere le tue pipeline CI/CD usando correttamente i segreti di GitHub Actions. Scopri le best practice per gestire in modo sicuro chiavi API e token di accesso.

Automatically translated with AI from the original post. Read the English original

Quando l'automazione viene eseguita completamente senza supervisione nel cloud, mantenere sicure le credenziali diventa fondamentale. Gestire in modo efficace i segreti di GitHub Actions garantisce che chiavi API, password di distribuzione e token di accesso restino fuori dal codice sorgente, rimanendo però facilmente accessibili ai workflow che ne hanno bisogno per compilare e rilasciare i progetti.

Punti chiave

• Non inserire mai password sensibili, chiavi API o token di accesso direttamente nei file YAML dei workflow.
• GitHub offre tre livelli di segreti: segreti di repository, segreti di organizzazione e segreti di ambiente.
• I segreti vengono cifrati prima ancora di raggiungere GitHub e vengono mascherati automaticamente nei log di esecuzione.
• I segreti di ambiente possono imporre un'approvazione umana prima che le credenziali di distribuzione diventino accessibili a un job.
• Segui sempre il principio del privilegio minimo, assegnando a ciascun segreto il numero più ridotto possibile di autorizzazioni necessarie.

Perché le credenziali in testo semplice non reggono in CI/CD

Quando hanno fretta di configurare una nuova pipeline, agli sviluppatori viene spesso la tentazione di incollare una chiave API direttamente nel file di configurazione del workflow. Dopotutto, se il workflow è privato, chi lo vedrà? Questo approccio introduce gravi vulnerabilità di sicurezza. I file dei workflow sono sottoposti a controllo di versione: ogni revisione storica, ogni commit e ogni branch conserva una traccia permanente di tutto ciò che è stato scritto in quei documenti YAML.

Inoltre, i repository cambiano spesso le autorizzazioni, passano da privati a pubblici o vengono sottoposti a fork da parte dei collaboratori. Se le tue credenziali sono memorizzate come stringhe di testo semplice nei file di configurazione, un singolo errore di configurazione dei permessi può esporre l'intero ambiente di produzione. Trattare i file di configurazione esclusivamente come istruzioni, conservando i dati sensibili in un vault cifrato e separato, è la regola fondamentale della sicurezza cloud moderna.

I tre livelli dei segreti di GitHub

GitHub riconosce che credenziali diverse hanno ambiti diversi. Per aiutare gli sviluppatori a gestire il controllo degli accessi in modo efficiente, la piattaforma consente di configurare i segreti su tre distinti livelli organizzativi.

Segreti a livello di repository

I segreti di repository appartengono esclusivamente a un singolo progetto. Se stai sviluppando un'applicazione autonoma o gestendo un singolo plugin, un segreto di repository mantiene le stringhe di connessione e i token di distribuzione bloccati in quello specifico spazio di lavoro. Non possono essere accessibili da altri progetti dell'organizzazione.

Segreti a livello di organizzazione

Quando più repository di un'azienda devono accedere alle stesse risorse condivise, come un registro di container centrale o un certificato aziendale per la firma del codice, i segreti di organizzazione ti evitano di duplicare le voci. Gli amministratori possono definire criteri e scegliere a quali repository o team è consentito ereditare queste credenziali a livello di organizzazione.

Segreti a livello di ambiente

I segreti di ambiente associano le credenziali a specifici obiettivi di distribuzione, come gli ambienti di staging o di produzione. È qui che conservi le chiavi necessarie per intervenire sui sistemi in esercizio. Un aspetto cruciale: i segreti di ambiente consentono di impostare revisori obbligatori, così che una persona debba approvare manualmente un'esecuzione di distribuzione prima che le credenziali di produzione vengano rese disponibili e consegnate al runner.

Come GitHub protegge i tuoi dati in transito

La sicurezza non riguarda solo dove vengono archiviati i segreti, ma anche come viaggiano durante l'esecuzione. I segreti vengono cifrati sulla tua macchina locale prima di essere trasmessi a GitHub, così non vengono mai inviati in chiaro sulla rete. Una volta archiviati, restano completamente nascosti nell'interfaccia delle impostazioni del repository.

Quando un workflow viene eseguito, devi passare esplicitamente un segreto a un passaggio o a un'azione indicandone il nome con la sintassi delle espressioni, ad esempio ${{ secrets.DATABASE_URL } }. Questo significa che un'azione di terze parti estranea o malevola del marketplace non può appropriarsi automaticamente di ogni credenziale del repository: riceve solo ciò che gli consegni tu esplicitamente.

Inoltre, GitHub analizza automaticamente i log di output dei job per mascherare le stringhe sensibili. Se il tuo script stampa per errore il valore di un segreto nella console, GitHub tenta di sostituire i caratteri con degli asterischi. Tuttavia, poiché gli script possono manipolare o codificare le stringhe prima di stamparle, affidarsi solo al mascheramento dei log non sostituisce la scrittura di codice sicuro.

Best practice per un'automazione sicura

Una gestione solida dei segreti di GitHub Actions richiede di adottare alcune abitudini quotidiane specifiche. Innanzitutto, distingui sempre tra un'impostazione di configurazione e un segreto. Se un valore è semplicemente un indirizzo di un sito web pubblico, il nome di un ambiente o un flag di funzionalità non sensibile, conservalo in testo normale all'interno del file YAML, così il team può leggere facilmente come funziona la pipeline. Riserva la funzionalità dei segreti esclusivamente ai dati che devono rimanere riservati.

In secondo luogo, adotta il principio del privilegio minimo. Genera token di accesso granulari con la scadenza più breve possibile e l'ambito di autorizzazioni più ristretto. Se un token di distribuzione deve solo scrivere in un bucket S3 specifico, non concedergli diritti amministrativi sull'intera infrastruttura cloud.

Conclusione

Padroneggiare la gestione dei segreti di GitHub Actions trasforma le tue pipeline CI/CD da potenziali punti deboli per la sicurezza in solidi motori di automazione di livello enterprise. Separando le credenziali dal codice e sfruttando controlli di accesso su più livelli, puoi rilasciare software rapidamente senza sacrificare la sicurezza.

Per approfondire i fondamenti della creazione di workflow automatizzati, dai un'occhiata a Ascolta l'episodio completo. Sintonizzati sulla discussione completa per saperne di più su come configurare trigger, job e runner per il tuo moderno ambiente cloud!

Domande frequenti

Posso leggere un segreto di GitHub Actions in una pull request proveniente da un fork?

Per impostazione predefinita, GitHub impedisce alle pull request di collaboratori esterni (fork) di accedere ai segreti del repository, per proteggere da codice malevolo che potrebbe rubare le tue credenziali.

Come passo un segreto da un workflow a un passaggio specifico?

Passi i segreti al workflow usando il contesto 'env' all'interno di un passaggio o di un job, associando il segreto di GitHub a una variabile di ambiente, ad esempio env: API_KEY: ${{ secrets.MY_API_KEY } }.

I segreti di GitHub Actions sono garantiti nascosti nei log?

GitHub maschera automaticamente i valori dei segreti noti nei log di esecuzione, ma non si tratta di una garanzia assoluta. Se un valore segreto viene manipolato, codificato o trasformato prima di essere stampato, alcune sue parti potrebbero essere esposte.

Qual è la differenza tra segreti del repository e segreti dell'ambiente?

I segreti del repository sono disponibili a qualsiasi workflow di un determinato repository, mentre i segreti dell'ambiente sono legati a specifici ambienti di distribuzione (come staging o produzione) e possono richiedere l'approvazione di una revisione manuale.