Hai rilasciato una nuova versione del plugin su GitHub, ma gli utenti sono fermi a quella vecchia. Scaricare ZIP a mano, caricare tramite il pannello di amministrazione, verificare la compatibilità: attività di routine che consumano tempo e generano errori.

Il meccanismo standard di aggiornamento di WordPress è legato alla directory ufficiale WordPress.org. Ma non tutti i plugin finiscono lì: soluzioni personalizzate per clienti, strumenti interni per team, fork di plugin noti con modifiche. Questi hanno bisogno di un percorso diverso.

Per fortuna, distribuire aggiornamenti direttamente da GitHub è stato risolto molto tempo fa. Ecco due metodi funzionanti: semplice (il plugin Git Updater, un paio di click) e avanzato (una classe PHP integrata per il pieno controllo).

💡 Panoramica rapida:

• Installa Git Updater: rileva i rilasci di GitHub come normali aggiornamenti di WordPress
• Per repository privati, configura un token di accesso nelle impostazioni del plugin
• Se stai scrivendo il tuo plugin e vuoi incorporare gli auto-aggiornamenti nel codice: usa la classe PHP integrata
• Il repository deve contenere un header del plugin valido e un tag di versione

Metodo 1: Git Updater, aggiornamenti in due click

Git Updater è un plugin gratuito che aggiunge il supporto per GitHub, Bitbucket, GitLab e Gitea alla schermata standard degli aggiornamenti di WordPress. Dopo l'installazione, i plugin e i temi da GitHub si aggiornano nello stesso posto di quelli normali: Bacheca → Aggiornamenti.

Lo sviluppatore Andy Fragen mantiene il progetto dal 2015. La pagina GitHub di Git Updater ha oltre 400 stelle e un repository attivo con commit regolari. La knowledge base su git-updater.com copre installazione, configurazione del token e utilizzo delle API.

L'installazione è semplice: scarica lo ZIP dal rilascio GitHub, caricalo tramite Plugin → Aggiungi nuovo → Carica plugin e attivalo. Il plugin inizia subito a tracciare i repository specificati negli header dei plugin e temi installati.

Per i repository privati, serve un token. Crea un Personal Access Token in Impostazioni GitHub → Impostazioni sviluppatore → Token (permessi: repo per privati; nessun token necessario per pubblici), incollalo in Impostazioni → Git Updater. Fatto questo, il plugin può vedere anche i repository chiusi.

Un dettaglio importante: Git Updater cerca tag nel formato X.Y.Z (versionamento semantico) nel repository. Se non ci sono tag, l'aggiornamento non funziona. Prima di un rilascio, imposta sempre un tag: git tag 1.2.0 && git push --tags.

Metodo 2: classe PHP integrata per sviluppatori

Se sei l'autore di un plugin e vuoi incorporare il meccanismo di auto-aggiornamento direttamente nel tuo codice (senza un plugin intermediario separato), l'approccio classico con la classe PHP funziona ancora. È più leggera della classe originale di Joachim Kudish e radishconcepts e usa gli hook nativi di WordPress.

Aggiungi il codice seguente al file principale del tuo plugin o a un file separato updater.php incluso via require_once:

1
/**
2
 * Auto-update from GitHub releases.
3
 * Place in main plugin file or include via require_once.
4
 */
5
function myplugin_check_github_update($transient) {
6
    if (empty($transient->checked)) {
7
        return $transient;
8
    }
9
 
10
    $plugin_slug = 'my-plugin/my-plugin.php';
11
    $github_repo = 'username/my-plugin';
12
 
13
    $response = wp_remote_get(
14
        'https://api.github.com/repos/' . $github_repo . '/releases/latest',
15
        array(
16
            'headers' => array(
17
                'Accept' => 'application/vnd.github.v3+json',
18
                'User-Agent' => 'WordPress/' . get_bloginfo('version'),
19
            ),
20
        )
21
    );
22
 
23
    if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {
24
        return $transient;
25
    }
26
 
27
    $release = json_decode(wp_remote_retrieve_body($response));
28
 
29
    if (!isset($release->tag_name)) {
30
        return $transient;
31
    }
32
 
33
    $latest_version = ltrim($release->tag_name, 'v');
34
    $current_version = $transient->checked[$plugin_slug] ?? '0';
35
 
36
    if (version_compare($latest_version, $current_version, '>')) {
37
        $transient->response[$plugin_slug] = (object) array(
38
            'slug'        => dirname($plugin_slug),
39
            'new_version' => $latest_version,
40
            'url'         => 'https://github.com/' . $github_repo,
41
            'package'     => $release->zipball_url,
42
        );
43
    }
44
 
45
    return $transient;
46
}
47
add_filter('pre_set_site_transient_update_plugins', 'myplugin_check_github_update');

Il codice fa esattamente tre cose: interroga l'API di GitHub per l'ultimo rilascio, confronta la versione da tag_name con la versione corrente del plugin e, se GitHub ne ha una più recente, registra l'aggiornamento nel meccanismo standard di WordPress. La versione del plugin è presa dall'header standard Version: X.Y.Z nel file principale.

Nota: per i repository pubblici non serve un token, ma l'API di GitHub senza token limita la frequenza delle richieste a 60 all'ora per IP. Per un plugin in produzione con molti utenti, aggiungi la cache dei risultati tramite set_transient() per 6-12 ore. Così non raggiungerai il limite ogni volta che qualcuno visita la pagina dei plugin.

Confronto degli approcci

Conclusione: se installi su un sito il plugin GitHub di qualcun altro, usa Git Updater. Se sei l'autore di un plugin e lo distribuisci tramite GitHub, incorpora gli auto-aggiornamenti nel codice così gli utenti non devono installare un plugin aggiuntivo.

Preparare il repository per gli auto-aggiornamenti

Qualunque metodo tu scelga, il repository GitHub deve essere preparato correttamente. Tre punti obbligatori:

• Header del plugin. Nel file PHP principale, includi l'header standard di WordPress: Plugin Name, Version, Author e Plugin URI con un link al repository. Git Updater legge Plugin URI e GitHub Plugin URI; specificane almeno uno.

• Tag di versione. Accompagna ogni rilascio con un tag: git tag 1.3.0 && git push origin 1.3.0. Senza tag, né Git Updater né la richiesta API vedranno la nuova versione.

• File Readme. Aggiungi un README.md con descrizione, changelog e link per l'installazione. Git Updater mostra il contenuto del readme nella schermata delle informazioni del plugin, facendo risparmiare tempo agli utenti che non devono visitare GitHub per le istruzioni.

Con GitHub Actions puoi andare oltre: al push di un tag, compila automaticamente lo ZIP, genera un changelog dai commit e crea un GitHub Release con l'archivio allegato. Un workflow già pronto è disponibile nella documentazione ufficiale di GitHub; adattalo per WordPress sostituendo il passo di build con il pacchettamento del plugin.

Il video mostra il processo completo dall'installazione di Git Updater al primo aggiornamento automatico del plugin. Consigliamo di guardarlo prima della configurazione: 12 minuti di registrazione schermo faranno risparmiare un'ora di tentativi.

⁉️🤔 Domande frequenti

Git Updater funziona con i plugin della directory ufficiale WordPress.org?

Sì, ma non ha senso. I plugin da WordPress.org ricevono già gli aggiornamenti tramite il meccanismo standard. Git Updater è specificamente per plugin e temi che non sono nella directory: sviluppi personalizzati, fork, plugin in fase di revisione.

Git Updater si può usare su un sito in produzione?

Sì, il progetto è stabile ed è mantenuto dal 2015. Prima di installarlo, fai un backup completo (come per ogni nuovo plugin). Su un sito di test, verifica l'aggiornamento di almeno un plugin, assicurati che i tag nel repository siano impostati correttamente e che l'aggiornamento si applichi senza errori.

Cosa succede se l'API di GitHub raggiunge il limite di richieste?

Per i repository pubblici, il limite è di 60 richieste all'ora da un IP. Git Updater mantiene le risposte in cache per 12 ore, quindi il problema si verifica raramente. Se dovesse accadere, crea un Personal Access Token gratuito (senza permessi aggiuntivi) e aggiungilo in Impostazioni → Git Updater: il limite sale subito a 5000 richieste all'ora.

Cosa fare se il plugin su GitHub usa dipendenze Composer?

Git Updater non esegue composer install durante gli aggiornamenti. Se il tuo plugin dipende da pacchetti Composer, incorpora l'autoloading tramite un bundle (inserisci vendor/ nello ZIP del rilascio) oppure aggiungi uno script post-aggiornamento che verifichi le dipendenze e avvisi l'amministratore se mancano.

Si possono aggiornare plugin da un repository privato su GitHub free?

Sì. Gli account GitHub gratuiti includono repository privati illimitati. Crea un Personal Access Token con permesso repo, aggiungilo a Git Updater e il plugin otterrà accesso ai tuoi repository privati.

Auto-aggiornamenti da GitHub: cosa usare nel 2026

Per il proprietario di un sito, la risposta è chiara: Git Updater. Gratuito, stabile, non richiede codice.

Per lo sviluppatore di un plugin, la scelta dipende dal pubblico. Se il tuo prodotto è installato da utenti comuni, incorpora la classe PHP di auto-aggiornamento direttamente nel codice del plugin. Un plugin intermediario in più nella catena riduce la conversione dell'installazione. Se il prodotto è per un pubblico tecnico, Git Updater come dipendenza è accettabile; basta menzionarlo nelle istruzioni.

Controlla subito i tuoi plugin su GitHub: ci sono i tag sugli ultimi rilasci, Plugin URI è compilato nell'header, l'utente ha un percorso di aggiornamento chiaro? Quindici minuti di configurazione faranno risparmiare a te e ai tuoi utenti la fatica manuale con gli archivi ZIP per gli anni a venire.