Deploy automatici con GitHub Actions e n8n

Panoramica

Un pipeline di deploy manuale è lento e soggetto a errori umani. Con n8n puoi orchestrare l'intero ciclo di rilascio: ricevere webhook da GitHub quando un push arriva su main, attivare il build e il deploy, gestire i rollback automatici in caso di fallimento, e notificare il team su Slack in tempo reale. Questa guida mostra come costruire un sistema di continuous deployment robusto e affidabile.

Prerequisiti

• Istanza n8n self-hosted accessibile da internet (per ricevere webhook GitHub)
• Repository GitHub con accesso admin per configurare i webhook
• Personal Access Token GitHub con permessi repo e workflow
• Server di produzione con accesso SSH da n8n
• Canale Slack dedicato ai deploy (ad esempio #deployments)
• Conoscenza base di Git, SSH e processi di deploy

Step 1: Configurare il webhook GitHub

Inizia creando il punto di ingresso: un nodo Webhook in n8n impostato su POST. Copia l'URL del webhook generato.

Vai nelle impostazioni del repository GitHub, sezione Webhooks, e aggiungi un nuovo webhook con:

• Payload URL: l'URL del webhook n8n
• Content type: application/json
• Secret: una stringa casuale che userai per verificare l'autenticità delle richieste
• Events: seleziona "Pushes" e "Pull request reviews"

Nella configurazione del nodo Webhook in n8n, aggiungi un nodo Code subito dopo che verifica la firma HMAC della richiesta usando il secret condiviso. Questo è fondamentale per la sicurezza: senza questa verifica, chiunque potrebbe attivare un deploy inviando una richiesta POST al tuo webhook.

Aggiungi un nodo IF che filtra solo gli eventi rilevanti: push sul branch main (o master) e pull request merged. Ignora i push su branch di feature per evitare deploy accidentali.

Step 2: Validazione pre-deploy

Prima di avviare il deploy, esegui una serie di controlli:

Controllo CI: usa il nodo HTTP Request per interrogare l'API GitHub e verificare che tutti i check del commit siano passati. Chiama l'endpoint /repos/{owner}/{repo}/commits/{sha}/check-runs e verifica che tutti i check abbiano conclusion "success". Se anche solo un check è fallito, blocca il deploy e notifica il team.

Controllo ambiente: usa un nodo SSH per verificare lo stato del server di produzione prima del deploy. Controlla che il disco abbia almeno il 20% di spazio libero, che la CPU non sia al 100%, e che il servizio web sia attivo. Qualsiasi anomalia deve bloccare il deploy.

Lock di deploy: per evitare deploy concorrenti, implementa un semplice sistema di lock. Prima di procedere, verifica tramite SSH che non esista un file /tmp/deploy.lock sul server. Se esiste, significa che un deploy è già in corso: manda un alert e fermati. Se non esiste, crea il file lock.

Step 3: Esecuzione del deploy

Il cuore del workflow è il processo di deploy. La strategia migliore dipende dal tuo stack, ma ecco un pattern robusto:

Backup pre-deploy: usa un nodo SSH per creare un backup della versione attuale. Esegui un comando che copia la directory corrente dell'applicazione in una cartella con timestamp, ad esempio cp -r /var/www/app /var/www/backups/app-$(date +%Y%m%d_%H%M%S). Salva il percorso del backup in una variabile del workflow per il rollback.

Pull del codice: esegui git pull origin main nella directory dell'applicazione tramite SSH. Usa l'opzione --ff-only per evitare merge accidentali.

Installazione dipendenze: esegui il comando appropriato per il tuo stack. Per un progetto Node.js: npm ci --production. Per PHP/Laravel: composer install --no-dev --optimize-autoloader. Per Python: pip install -r requirements.txt.

Build degli asset: se il progetto ha un frontend, esegui il build. Per esempio: npm run build. Questo step può richiedere tempo, quindi imposta un timeout adeguato sul nodo SSH (almeno 5 minuti).

Migrazioni database: se ci sono migrazioni pendenti, eseguile con cautela. Per Laravel: php artisan migrate --force. Questo è lo step più delicato perché le migrazioni non sono sempre facilmente reversibili.

Restart dei servizi: riavvia il web server o il process manager. Per PM2: pm2 restart all. Per systemd: sudo systemctl restart myapp.

Ogni step deve essere un nodo SSH separato con "Continue on Fail" attivato, in modo da poter gestire gli errori individualmente.

Step 4: Health check post-deploy

Dopo il deploy, verifica che l'applicazione funzioni correttamente:

Aggiungi un nodo Wait di 30 secondi per permettere al servizio di avviarsi completamente.

Poi usa un nodo HTTP Request per chiamare l'endpoint di health check dell'applicazione. Verifica che:

• Il codice di risposta sia 200
• Il body contenga la risposta attesa
• Il tempo di risposta sia sotto i 3 secondi

Se il health check fallisce dopo 3 tentativi (usa un nodo Code con un contatore), attiva la procedura di rollback.

Step 5: Rollback automatico

Se qualcosa va storto durante il deploy o il health check fallisce, il rollback deve essere automatico e rapido:

1. Usa un nodo SSH per ripristinare il backup creato nello step 3. Sostituisci la directory dell'applicazione con il backup.
2. Reinstalla le dipendenze della versione precedente.
3. Se sono state eseguite migrazioni database, esegui il rollback: php artisan migrate:rollback per Laravel, o lo script equivalente per il tuo stack.
4. Riavvia i servizi.
5. Esegui nuovamente il health check per confermare che il rollback è riuscito.
6. Rimuovi il file di lock del deploy.

In caso di fallimento anche del rollback (scenario critico), invia un alert di massima priorità su tutti i canali disponibili: Slack, Telegram e email al team tecnico.

Step 6: Notifiche Slack in tempo reale

Configura le notifiche per ogni fase del deploy. Usa il nodo Slack con Block Kit per messaggi ricchi e informativi:

Inizio deploy: messaggio con commit SHA, autore, messaggio del commit e link al diff su GitHub. Stato: "In corso".

Deploy completato: aggiorna il messaggio originale (o invia uno nuovo) con stato "Successo", durata del deploy e link diretto all'applicazione.

Deploy fallito: messaggio con stato "Fallito", step in cui si è verificato l'errore, log dell'errore e indicazione se il rollback è stato eseguito con successo.

Rollback eseguito: messaggio dedicato che conferma il ripristino alla versione precedente.

Per aggiornare il messaggio originale invece di inviarne uno nuovo, salva il timestamp del messaggio Slack restituito dal primo invio e usalo nell'operazione "Update Message" per i messaggi successivi.

Step 7: Cleanup e log

Al termine del processo (successo o fallback), esegui le operazioni di pulizia:

• Rimuovi il file /tmp/deploy.lock tramite SSH
• Registra il deploy in un foglio Google Sheets con: data, commit SHA, autore, esito, durata, eventuali errori
• Mantieni solo gli ultimi 10 backup sulla macchina per non saturare il disco: usa un comando che elimina i backup più vecchi

Questo log storico è prezioso per analizzare la frequenza dei deploy, il tasso di fallimento e il tempo medio di rilascio. Metriche fondamentali per migliorare continuamente il processo.