Aggiornare plugin WordPress custom da GitHub, senza processi manuali
Per anni ho gestito gli aggiornamenti dei miei plugin custom nello stesso modo: scaricare lo ZIP, andare su ogni sito, disinstallare la versione vecchia, caricare quella nuova. Funziona. Ma scala malissimo, non lascia traccia di nulla, e basta un sito dimenticato per ritrovarsi con versioni divergenti tra ambienti diversi.
Il problema non è tecnico in sé è che i plugin su wordpress.org ottengono tutta l’infrastruttura di distribuzione gratuitamente: notifiche native, aggiornamento con un clic, cronologia delle versioni. I plugin custom non hanno nulla di tutto questo. Ho deciso di costruirmela.
Il problema con i plugin custom
Quando un plugin è su wordpress.org, WordPress sa tutto: versione corrente, versione disponibile, changelog. Sa quando aggiornare e mostra la notifica nell’admin. Quando il plugin è un repository GitHub privato, WordPress non sa che esiste.
Il risultato pratico: nessuna notifica di aggiornamento, nessun log di quando è stata installata l’ultima versione, nessuna visibilità su quale sito ha quale versione. Ogni correzione di bug richiede un intervento manuale su ogni installazione e se ne dimentichi una, il bug rimane in produzione a tempo indeterminato.
L’idea: usare GitHub come server di aggiornamenti
GitHub Releases esiste già per fare esattamente quello che mi serve: versionare software, allegare ZIP, scrivere changelog. L’unica cosa che mancava era il collegamento con il meccanismo nativo degli aggiornamenti di WordPress.
WordPress espone dei filtri precisi per questo: pre_set_site_transient_update_plugins intercetta il momento in cui il core controlla gli aggiornamenti disponibili. Da qui si può iniettare informazioni su plugin non presenti su wordpress.org, facendoli apparire nell’elenco degli aggiornamenti esattamente come i plugin ufficiali.
La logica è su tre livelli:
Aggiornamento quando esce una nuova release su GitHub, WordPress mostra la notifica nell’admin; l’aggiornamento avviene con il pulsante standard
Scoperta il plugin cerca su GitHub i repository taggati con un topic configurabile, e identifica quali sono installati localmente
Identificazione ogni plugin custom include un header speciale nel file principale che dichiara il suo repository di appartenenza
Le sfide reali durante lo sviluppo
La parte concettuale era chiara. L’implementazione ha riservato alcune sorprese.
Il problema del nome cartella. GitHub genera lo ZIP di una release con un nome che include il suffisso del branch o del tag (es. wp-alarm-system-v1.8.zip). WordPress, durante l’installazione, si aspetta che la cartella estratta corrisponda allo slug del plugin. Senza una gestione esplicita di questo passaggio, il plugin viene installato in una cartella dal nome sbagliato e non viene riconosciuto.
Autenticazione sui repository privati. Un token GitHub non basta: bisogna sapere dove usarlo e quando. Le chiamate all’API GitHub per recuperare le informazioni sulla release usano header di autenticazione diversi rispetto al download dello ZIP allegato. Gestirli nello stesso flusso senza esporre il token nel markup HTML richiede attenzione.
Il toggle “Enable auto-updates”. WordPress mostra questa opzione solo per i plugin che compaiono correttamente nei transient response o no_update. Se la struttura dei dati iniettata non è esattamente quella attesa, il toggle non appare. La documentazione ufficiale non lo spiega in modo chiaro l’ho scoperto leggendo il core.
Cosa cambia nella pratica
Il cambiamento principale non è tecnico, è procedurale. Invece di gestire manualmente la distribuzione di ogni aggiornamento, il flusso diventa: si crea una nuova release su GitHub, si assegna un tag di versione, si carica il file. Da quel momento, ogni sito WordPress che usa quel plugin vede l’aggiornamento disponibile e può installarlo con un clic.
Per chi distribuisce plugin custom su più siti propri o di clienti questo elimina una fonte di attrito significativa e introduce un sistema di versioning strutturato che prima non esisteva.
L’interfaccia admin
Il plugin aggiunge una sezione dedicata nell’admin WordPress con quattro aree:
- Plugin installati stato e versione dei plugin gestiti tramite l’updater
- Catalogo disponibile repository GitHub disponibili per l’installazione
- Configurazione token GitHub e topic di scoperta
- Log cronologia degli aggiornamenti con versione di partenza e versione installata
Il log è la parte che uso di più: risponde alla domanda “quando è stato aggiornato l’ultimo sito e da quale versione?” senza dover aprire ogni installazione.
Il ciclo di distribuzione in pratica
Con il sistema attivo, distribuire una nuova versione di un plugin richiede:
- Fare commit e push delle modifiche su GitHub
- Creare una release con tag di versione (
v1.9,v2.0) - Allegare lo ZIP alla release
WordPress rileva la nuova versione entro il ciclo di controllo standard e mostra la notifica nell’admin di ogni sito che ha il plugin installato. L’aggiornamento avviene con un clic, come per qualsiasi plugin da wordpress.org.
Quando ha senso costruirsi questa infrastruttura
Questo approccio vale la pena quando si mantengono più plugin custom su più siti. Per un singolo plugin su un singolo sito, l’aggiornamento manuale è ragionevole. Per tre o quattro plugin distribuiti su cinque o sei ambienti, il costo dell’aggiornamento manuale supera abbastanza in fretta il costo di costruire il sistema.
Alternative commerciali come EDD Software Licensing o Freemius fanno cose simili e molto di più, ma aggiungono complessità e dipendenze esterne. Per un ecosistema di plugin interni, un sistema custom da 400 righe di codice è più controllabile e più facile da adattare.
Il codice è privato per ora, ma se stai affrontando lo stesso problema puoi scrivermi a info@davidemugnaini.it sono disponibile a discutere l’architettura o a condividere parti del codice.