Creare una pipeline CI/CD minimale con GitHub Actions

AI Editor · 13 luglio 2026

Automatizzare l’integrazione e la distribuzione continua è un passaggio fondamentale per gestire progetti software in modo professionale. GitHub Actions consente di definire i flussi di lavoro direttamente nel repository, riducendo la dipendenza da strumenti esterni e mantenendo il controllo sul codice di automazione. Questa guida mostra come creare una pipeline CI/CD essenziale con GitHub Actions, concentrandosi sugli elementi indispensabili senza aggiungere complessità superflue. Prerequisiti e preparazione dell’ambiente Per iniziare serve un repository su GitHub con permessi di scrittura. Il progetto deve contenere almeno un file di configurazione del linguaggio o del framework in uso, come package.json per Node.js o requirements.txt per Python. Non sono necessari plugin aggiuntivi: GitHub Actions è disponibile su tutti i repository, pubblici e privati. È consigliabile verificare che il repository sia collegato a un branch principale stabile, tipicamente main o master, in modo da testare i trigger su eventi reali di push o pull request fin dalle prime configurazioni. Può essere utile creare un branch dedicato alle prove iniziali, per isolare le modifiche al workflow dal codice di produzione. Struttura di base di un workflow Un workflow si definisce con un file YAML posizionato nella cartella.github/workflows. Il nome del file può essere descrittivo, ad esempio ci-minimal.yml. La struttura prevede tre sezioni principali: il nome del workflow, gli eventi che lo attivano e i job da eseguire. Per una pipeline minimale i trigger più comuni sono il push sul branch principale e l’apertura di una pull request. Questi eventi garantiscono che ogni modifica venga verificata automaticamente. È possibile estendere i trigger con filtri su path o tag per limitare l’esecuzione solo quando necessario. Esempio di configurazione iniziale name: Pipeline minimale on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout del codice uses: actions/checkout@v4 Il runner ubuntu-latest fornisce un ambiente pulito e aggiornato per la maggior parte dei progetti. Il passo di checkout recupera il codice sorgente nel workspace del runner, rendendolo disponibile per le fasi successive. La versione dell’azione checkout può influenzare la compatibilità con repository di grandi dimensioni o con submodule. Implementazione dei job per build e test Una pipeline minimale deve almeno compilare il codice e verificare che i test passino. Per un’applicazione Node.js si aggiungono i passi per installare le dipendenze ed eseguire i test. Il comando npm ci garantisce un’installazione deterministica basata sul file lock. jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Configura Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Installa dipendenze run: npm ci - name: Esegui test run: npm test Per i progetti Python la sequenza cambia leggermente, sostituendo i comandi con pip install e pytest. L’importante è mantenere i passi sequenziali e leggibili, in modo che eventuali errori siano immediatamente attribuibili a una fase specifica. L’uso di shell esplicite (bash o pwsh) aiuta a controllare il comportamento su sistemi operativi diversi. Aggiunta di controlli di qualità Per aumentare il valore della pipeline senza appesantirla, si può inserire un controllo di linting. Questo passaggio contribuisce a mantenere standard di codice uniformi prima che le modifiche raggiungano il branch principale. Il comando specifico varia in base al progetto, ma l’approccio resta lo stesso: eseguire uno script definito nel package.json o nel file equivalente. Gestione degli artefatti e persistenza dei risultati Quando la build genera file da conservare, come pacchetti o report di test, è utile utilizzare l’azione ufficiale per caricare gli artefatti. In questo modo i risultati possono essere scaricati in un secondo momento senza dover rieseguire l’intera pipeline. Gli artefatti rimangono disponibili per un periodo limitato, sufficiente per la maggior parte dei casi di verifica manuale o di passaggio a fasi successive. - name: Carica artefatti uses: actions/upload-artifact@v4 with: name: build-output path: dist/ Estensione minimale verso il deployment Una volta verificata la qualità del codice, la pipeline può procedere con un deployment controllato. Per mantenere il carattere minimale si può configurare un job separato che si attiva solo dopo il completamento positivo del job di build. La condizione needs garantisce che il deployment avvenga solo se la fase precedente ha avuto esito positivo, mentre la clausola if sul branch principale evita deploy accidentali da feature branch. deploy: needs: build runs-on: ubuntu-latest if: github.ref == 'refs/heads/main' steps: - uses: actions/checkout@v4 - name: Deploy su ambiente di staging run: | echo "Esecuzione deploy minimale" # Comando di deploy specifico del progetto Utilizzo di segreti e variabili di ambiente Le credenziali necessarie per il deployment non devono mai essere inserite direttamente nel file YAML. GitHub permette di definire segreti a livello di repository o di organizzazione, accessibili tramite la sintassi ${{ secrets.NOME_SEGRETO }}. Per le variabili non sensibili, come URL di endpoint o nomi di ambiente, si possono invece utilizzare le variabili di repository. Questo approccio mantiene il file di configurazione pulito e riduce il rischio di esposizione accidentale. Debugging e analisi dei risultati Quando un workflow fallisce, i log dettagliati sono disponibili direttamente nell’interfaccia di GitHub. Ogni step mostra l’output dei comandi eseguiti, facilitando l’identificazione del punto di rottura. Per casi più complessi si può attivare il debug impostando la variabile di ambiente ACTIONS_STEP_DEBUG su true. È consigliabile esaminare regolarmente i tempi di esecuzione dei job: pipeline troppo lente possono essere ottimizzate riducendo il numero di passi o utilizzando la cache per le dipendenze. Esempio di caching delle dipendenze - name: Cache dipendenze uses: actions/cache@v4 with: path: ~/.npm key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} Il caching riduce significativamente i tempi di installazione nelle esecuzioni successive, senza modificare la logica della pipeline. È importante scegliere chiavi di cache stabili ma aggiornate quando cambiano le dipendenze. buone pratiche per mantenere la pipeline snella Una pipeline minimale deve rimanere leggibile e manutenibile nel tempo. È preferibile limitare l’uso di azioni di terze parti e privilegiare quelle ufficiali mantenute da GitHub. Quando si utilizzano azioni esterne, è buona norma verificare la reputazione del maintainer e il numero di stelle del repository. Separare i job logici (verifica del codice, build e deployment) permette di eseguirli in parallelo quando possibile e di riutilizzare parti della configurazione in workflow diversi. Documentare il workflow con commenti all’interno del file YAML aiuta i membri del team a comprendere rapidamente lo scopo di ogni sezione, soprattutto quando il progetto coinvolge più collaboratori. Considerazioni sulla scalabilità futura Anche se l’obiettivo iniziale è mantenere la pipeline minimale, è utile progettare la struttura in modo che possa crescere. L’uso di job riutilizzabili e template di workflow permette di aggiungere nuove fasi senza duplicare codice. GitHub Actions supporta l’importazione di workflow da altri repository, facilitando la standardizzazione tra più progetti. Per ambienti con esigenze di risorse elevate si può valutare l’utilizzo di self-hosted runner, tenendo però presente le responsabilità aggiuntive di manutenzione dell’infrastruttura. Conclusione Costruire una pipeline CI/CD minimale con GitHub Actions permette di automatizzare le verifiche essenziali senza introdurre complessità eccessiva. La configurazione mostrata in questa guida copre i passaggi fondamentali: checkout del codice, installazione delle dipendenze, esecuzione dei test, gestione degli artefatti e deployment controllato. Seguendo un approccio graduale e mantenendo il file di configurazione pulito, è possibile estendere la pipeline in base alle esigenze reali del progetto.