Come funziona la baracca

C'è qualcosa di profondamente soddisfacente nel premere "push" e sapere che, nel giro di pochi minuti, il tuo sito sarà aggiornato. Nessun FTP da aprire, nessun server da configurare, nessun file da copiare manualmente. Solo tu, il tuo codice, e un sistema che fa tutto il lavoro sporco al posto tuo.

È esattamente quello che ho fatto in modo che succeda con questo sito: scrivo un articolo in Markdown, faccio commit e push, e il sito si aggiorna da solo. Sembra magia, ma è solo GitHub Actions che fa il suo lavoro. E la cosa bella è che questa "magia" è accessibile a chiunque, gratuitamente.

In questo articolo vi racconto come ho configurato il sistema di pubblicazione automatica, con un twist interessante: il codice sorgente e il sito pubblicato vivono in due repository separati.

Perché Separare Sorgente e Pubblicazione

Quando ho iniziato a pensare di utilizzare GitHub Pages per l'hosting di questo sito, mi sono trovato di fronte a una scelta: tenere tutto nello stesso repository o separare il codice sorgente dal sito pubblicato.

La prima opzione è la più semplice: hai un solo repository, e GitHub Pages pubblica direttamente da lì. È l'approccio che va bene per la maggior parte dei progetti. Ma nel mio caso c'erano alcune considerazioni che mi hanno spinto verso la seconda strada.

Separazione delle responsabilità: il repository sorgente contiene TypeScript, configurazioni di build, file di sviluppo, test. Niente di tutto questo serve al sito finale. Mescolando le due cose, il repository diventa confuso e il suo scopo meno chiaro.

Privacy selettiva: magari vuoi che il codice sorgente rimanga privato, ma il sito deve essere pubblico. Con repository separati, questa distinzione è naturale.

Storico git più pulito: il repository di pubblicazione contiene solo i file HTML, CSS e JavaScript generati. Ogni commit rappresenta una nuova versione del sito, senza il "rumore" dei commit di sviluppo.

Flessibilità: puoi avere più repository sorgente che pubblicano sullo stesso sito, o un sorgente che pubblica su più destinazioni diverse.

Perchè GitHub Pages

Prima di addentrarci nell'automazione, vale la pena ricordare perché GitHub Pages è una scelta ideale per siti statici come blog e portfolio.

È gratuito. Per repository pubblici, non paghi nulla. Zero. Niente canoni mensili, niente costi a consumo, niente sorprese in bolletta.

HTTPS automatico. Il certificato SSL viene generato e rinnovato automaticamente. Il tuo sito sarà sempre accessibile via HTTPS senza che tu debba fare nulla.

CDN globale. I tuoi file vengono distribuiti su server in tutto il mondo. Un visitatore dal Giappone e uno dall'Italia riceveranno i contenuti da server vicini a loro, con tempi di caricamento ottimali.

Affidabilità. L'infrastruttura di GitHub è robusta. Il tuo sito sarà online praticamente sempre, senza che tu debba preoccuparti di uptime, backup o disaster recovery.

Domini personalizzati. Puoi collegare il tuo dominio personale con pochi click. GitHub si occupa anche del certificato HTTPS per il dominio custom.

Certo, ci sono limiti: 1GB di spazio, 100GB di banda al mese, niente contenuti dinamici. Ma per un blog personale o un portfolio, questi limiti sono più che sufficienti. E se un giorno dovessi superarli, beh, complimenti: hai un problema che la maggior parte dei blogger vorrebbe avere.

GitHub Actions, cos'è?

GitHub Actions è il sistema di automazione integrato in GitHub. Puoi pensarlo come un maggiordomo digitale: gli dai una lista di istruzioni, e lui le esegue fedelmente ogni volta che si verifica un certo evento.

Nel nostro caso, l'evento è un push sul branch principale. Le istruzioni sono: prendi il codice, genera il sito, pubblicalo.

Le Actions sono definite in file YAML nella cartella .github/workflows/ del repository. Ogni file descrive un "workflow", una sequenza di operazioni da eseguire.

La cosa bella è che questi workflow vengono eseguiti su macchine virtuali messe a disposizione da GitHub. Non devi configurare server, non devi installare software, non devi preoccuparti di nulla. Definisci cosa vuoi fare, e GitHub si occupa del come.

Anatomia di un Workflow di Deploy

Vediamo come funziona un workflow che genera un sito statico e lo pubblica su un repository esterno. Non vi mostrerò il codice esatto (ogni progetto ha le sue specificità), ma vi spiego il flusso logico.

Trigger: Quando Si Attiva

Il workflow si attiva in due modi:

  1. Automaticamente quando fai push sul branch principale
  2. Manualmente dalla tab Actions su GitHub (utile per forzare un deploy)

La possibilità di trigger manuale è sottovalutata. A volte vuoi ricostruire il sito senza modificare nulla, magari perché hai aggiornato qualcosa nel repository di destinazione. Con un click, puoi farlo.

Fase 1: Preparazione dell'Ambiente

La prima cosa che fa il workflow è preparare l'ambiente di lavoro:

  1. Checkout: scarica il codice sorgente dal repository
  2. Setup Node.js: installa la versione corretta di Node.js
  3. Installazione dipendenze: esegue npm ci per installare le dipendenze in modo riproducibile

Questa fase è identica per qualsiasi progetto Node.js. La magia inizia dopo.

Fase 2: Generazione del Sito

Qui entra in gioco la logica specifica di SimplePress:

  1. Pulizia: rimuove eventuali build precedenti
  2. Build: compila TypeScript e genera le pagine HTML

Al termine di questa fase, la cartella build/ contiene il sito statico completo, pronto per essere pubblicato.

Fase 3: Pubblicazione sul Repository Esterno

Questa è la parte interessante. Il workflow deve prendere i file generati e copiarli su un repository completamente diverso. Come fa?

GitHub Actions mette a disposizione "actions" predefinite, piccoli moduli riutilizzabili che fanno operazioni comuni. Una di queste, molto popolare, permette di pubblicare file su GitHub Pages, anche su repository esterni.

L'action:

Dal punto di vista del repository di destinazione, è come se qualcuno avesse fatto un commit con i nuovi file. Semplice, pulito, tracciabile.

La Questione della Sicurezza

Per permettere a un workflow di scrivere su un altro repository, servono delle credenziali. Non puoi semplicemente fare push su un repository qualsiasi (per fortuna!).

Ci sono due approcci principali:

Personal Access Token

È un token che generi dal tuo account GitHub e che dà accesso ai tuoi repository. Lo memorizzi come "secret" nel repository sorgente, e il workflow lo usa per autenticarsi.

Pro: semplice da configurare. Contro: dà accesso a tutti i tuoi repository (o a tutti quelli pubblici), non solo a quello di destinazione.

Deploy Keys

Sono chiavi SSH specifiche per un singolo repository. Ne generi una, aggiungi la parte pubblica al repository di destinazione come "deploy key", e memorizzi la parte privata come secret nel repository sorgente.

Pro: accesso limitato al solo repository di destinazione, più sicuro. Contro: richiede qualche passaggio in più per la configurazione.

Per un progetto personale, entrambi gli approcci funzionano. Se sei particolarmente attento alla sicurezza, le Deploy Keys sono la scelta migliore. Io preferisco questo approccio: il principio del minimo privilegio è sempre una buona pratica.

Il Flusso Completo in Azione

Ricapitoliamo cosa succede quando faccio push di un nuovo articolo:

  1. Push: il commit arriva sul repository sorgente
  2. Trigger: GitHub Actions rileva il push e avvia il workflow
  3. Checkout: il codice viene scaricato sulla macchina virtuale
  4. Setup: Node.js viene configurato, le dipendenze installate
  5. Build: SimplePress genera il sito statico
  6. Deploy: i file vengono copiati sul repository di pubblicazione
  7. GitHub Pages: rileva il nuovo commit e aggiorna il sito

Tutto questo succede in pochi minuti, senza alcun intervento manuale. Posso scrivere un articolo dal telefono, fare commit da una web interface, e il sito si aggiorna comunque.

Vantaggi Inaspettati

Oltre ai benefici ovvi (automazione, comodità), questo setup ha alcuni vantaggi meno scontati:

Rollback facile: ogni deploy è un commit nel repository di pubblicazione. Se qualcosa va storto, basta fare revert all'ultimo commit buono e il sito torna come prima.

Audit trail: puoi vedere esattamente quando ogni versione del sito è stata pubblicata, e quale commit sorgente l'ha generata.

Collaborazione semplificata: se un giorno volessi accettare contributi, i collaboratori potrebbero aprire pull request sul repository sorgente. Il deploy avverrebbe solo dopo il merge, mantenendo il controllo su cosa viene pubblicato.

Ambienti multipli: potresti configurare workflow diversi per branch diversi. Ad esempio, il branch develop potrebbe pubblicare su un sito di staging, mentre main pubblica su produzione.

Considerazioni Pratiche

Se state pensando di implementare un sistema simile, ecco alcuni consigli pratici:

Testare localmente prima di pushare. Assicuratevi che il build funzioni sul vostro computer prima di affidarvi all'automazione. Debugging di workflow falliti è meno divertente di quanto sembri.

Usare npm ci invece di npm install. Il primo è più veloce e garantisce build riproducibili, usando esattamente le versioni specificate nel lockfile.

Abilitare il caching delle dipendenze. GitHub Actions può memorizzare le dipendenze npm tra un'esecuzione e l'altra, velocizzando significativamente i build successivi.

Monitorare i workflow. Ogni tanto date un'occhiata alla tab Actions. Se qualcosa fallisce, lo saprete solo guardando lì (a meno che non configuriate notifiche, che è un'altra buona idea).

Conclusioni

L'automazione del deploy è uno di quegli investimenti che ripagano ogni singolo giorno. Il tempo speso a configurare il workflow viene recuperato rapidamente, e soprattutto elimina quella frizione psicologica che a volte ci impedisce di pubblicare.

Quando sai che pubblicare significa semplicemente "commit e push", pubblichi di più. Quando non devi preoccuparti del deploy, puoi concentrarti su quello che conta davvero: i contenuti.

GitHub Actions e GitHub Pages formano un'accoppiata potente per chiunque gestisca un sito statico. Sono gratuiti, affidabili, e una volta configurati spariscono sullo sfondo, facendo il loro lavoro in silenzio.

La separazione tra repository sorgente e repository di pubblicazione aggiunge un livello di pulizia architetturale che apprezzo particolarmente. Non è necessaria per tutti, ma se vi trovate a gestire progetti dove la distinzione tra "sviluppo" e "produzione" è importante, è un pattern da considerare.

E la prossima volta che fate push e il vostro sito si aggiorna da solo, prendetevi un momento per apprezzare la magia. Anche se sapete esattamente come funziona, resta comunque un po' magica.