Esegui il deploy da GitHub o GitLab con Plesk
Collega un repository GitHub o GitLab a Plesk, esegui il deploy del tuo sito manualmente o automaticamente a ogni push grazie a un webhook e correggi gli errori più frequenti.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come collegare un repository GitHub o GitLab al tuo sito Plesk. Una volta completata la configurazione, basta un semplice git push per aggiornare il sito.
Il principio è il seguente: invii le modifiche a GitHub o GitLab, Plesk recupera i nuovi commit e copia i file del branch attivo nella cartella del tuo sito.
Prerequisiti
- Un accesso al tuo pannello Plesk (vedi Connetti all'interfaccia Plesk).
- Un repository GitHub o GitLab che contiene il tuo sito.
- I diritti di amministrazione del repository per aggiungere una chiave e un webhook. Su GitLab serve il ruolo Maintainer o Owner.
Questa guida usa httpdocs, la cartella abituale del dominio principale. Per un dominio aggiuntivo la cartella può essere diversa: controlla la Root del documento in Hosting e DNS > Hosting.
Passaggio 1: prepara il repository
Il contenuto della radice del repository viene copiato nella cartella di destinazione, /httpdocs per impostazione predefinita. Un file index.html nella radice del repository diventa quindi httpdocs/index.html.
Non inserire mai nel controllo di versione i tuoi segreti né i file generati. Ecco un esempio di .gitignore:
.env
node_modules/
vendor/
*.logI file ignorati da Git non vengono distribuiti. Un file .env deve quindi essere creato direttamente sul server.
Passaggio 2: aggiungi il repository in Plesk
- Vai su Siti web e domini e individua il tuo dominio.
- Clicca su Git. Se esiste già un repository, clicca su Aggiungi archivio.
- Seleziona Hosting git remoto come GitHub o BitBucket. Questa opzione è adatta anche a GitLab.
- Nel campo del repository remoto, inserisci l'indirizzo del tuo repository.
| Tipo di repository | Formato dell'indirizzo |
|---|---|
| Pubblico | https://github.com/tuo-account/mio-sito.git |
| Privato, GitHub | git@github.com:tuo-account/mio-sito.git |
| Privato, GitLab | git@gitlab.com:tuo-account/mio-sito.git |
Per un repository privato è consigliato il formato SSH: Plesk genera una chiave e mostra il campo Chiave pubblica SSH. Non confermare ancora e passa al passaggio 3.
Passaggio 3: autorizza Plesk a leggere un repository privato
Copia il contenuto del campo Chiave pubblica SSH, poi aggiungilo come deploy key.
Su GitHub:
- Apri il repository, poi Settings > Deploy keys.
- Clicca su Add deploy key.
- Assegna un nome alla chiave in Title, ad esempio
Plesk, e incolla la chiave in Key. - Lascia deselezionato Allow write access: a Plesk basta leggere il repository.
- Clicca su Add key.
Su GitLab:
- Apri il progetto, poi Settings > Repository.
- Espandi Deploy keys e seleziona Add new key.
- Assegna un nome alla chiave e incollala.
- Lascia deselezionato Grant write permissions to this key, poi salva.
Passaggio 4: scegli la modalità di deploy
Di nuovo in Plesk, nella sezione Il tuo sito web:
-
Scegli la Modalità di implementazione:
Modalità Effetto Implementazione automatica I commit recuperati vengono pubblicati immediatamente Implementazione manuale I commit vengono recuperati, ma pubblicati solo quando lo richiedi Nessuna implementazione (hosting di archivio) Non viene pubblicato nulla -
Controlla la Directory di destinazione. Lascia
/httpdocsper un sito standard. -
Clicca su OK. Plesk clona quindi il repository.
Per un sito in produzione, la modalità manuale è più prudente finché il tuo processo non è collaudato: con la modalità automatica, qualsiasi errore inviato al branch attivo va subito online.
Passaggio 5: seleziona il branch ed esegui il deploy
- Nella pagina Git, clicca su Cambia ramificazione e percorso.
- In Ramificazione, seleziona il tuo branch di produzione, ad esempio
main, poi conferma. - Clicca su Estrai aggiornamenti.
- In modalità manuale, clicca su Implementa da archivio (o Implementa).
Viene distribuito solo il branch attivo.
Passaggio 6: automatizza con un webhook
Senza webhook, Plesk non sa che esiste un nuovo commit e devi cliccare su Estrai aggiornamenti. Il webhook lo avvisa a ogni git push.
In Plesk, clicca su Impostazioni archivio e copia l'URL del webhook. Trattalo come un segreto: chiunque lo conosca può avviare un recupero.
Su GitHub:
- Apri Settings > Webhooks, poi clicca su Add webhook.
- Incolla l'indirizzo in Payload URL.
- In Content type, scegli
application/json. - Mantieni l'invio del solo evento
push(Just the push event). - Verifica che Active sia selezionato, poi clicca su Add webhook.
Su GitLab:
- Apri Settings > Webhooks, poi seleziona Add new webhook.
- Incolla l'indirizzo in URL.
- In Trigger, seleziona Push events.
- Lascia attivo Enable SSL verification se il certificato di Plesk è valido.
- Seleziona Add webhook.
Passaggio 7: esegui azioni dopo il deploy
Alcuni progetti richiedono un'azione dopo la copia dei file, come riavviare un'applicazione o svuotare una cache.
- In Impostazioni archivio, seleziona Abilita azioni di implementazione aggiuntive.
- Inserisci un comando per riga.
Ad esempio, per riavviare un'applicazione Node.js la cui cartella è httpdocs:
cd httpdocs
mkdir -p tmp
touch tmp/restart.txtPer installare le dipendenze e compilare lo stesso progetto, sostituendo 24 con la versione di Node.js in uso:
export PATH=/opt/plesk/node/24/bin:$PATH
cd httpdocs
npm ci
npm run build
mkdir -p tmp
touch tmp/restart.txtPer un progetto Laravel, consulta Ospita un sito Laravel su Plesk.
Verifica il risultato
-
Modifica un file visibile, poi invia la modifica:
Terminalegit add . git commit -m "Test del deploy" git push origin main -
In Plesk, nella pagina Git, verifica che l'ultimo commit mostrato sia il tuo. Registri di commit presenta la cronologia.
-
Ricarica
https://tuo-dominio.com/e controlla la modifica. -
Verifica la consegna del webhook:
- GitHub: Settings > Webhooks, apri il webhook, poi Recent deliveries;
- GitLab: Settings > Webhooks, Edit, poi Recent events. Il pulsante Test > Push events consente anche di inviare una prova.
Torna a una versione precedente
Annulla il commit errato, poi invia il risultato:
git revert HEAD
git push origin mainUn nuovo deploy ripristina i file. Se sono state eseguite migrazioni del database, questa operazione non le annulla.
Risoluzione dei problemi
Permission denied (publickey)
La chiave pubblica di Plesk non è stata aggiunta al repository, oppure è stata aggiunta a un altro repository. Copiala di nuovo da Plesk e controlla l'elenco delle deploy key.
Key is already in use su GitHub
Questa deploy key è già associata a un altro repository. Rimuovila da quel repository oppure aggiungila a un account GitHub dedicato.
Repository not found o Authentication failed
L'indirizzo non è corretto, il repository è privato mentre usi un indirizzo HTTPS senza credenziali, oppure il token è scaduto. Poiché l'indirizzo di un repository non può essere modificato in Plesk, eliminalo con Rimuovi archivio e aggiungilo di nuovo. I file già pubblicati vengono conservati.
Il push non produce alcun aggiornamento
Verifica nell'ordine:
- che il commit sia stato inviato al branch attivo;
- che la modalità non sia Implementazione manuale o Nessuna implementazione;
- che il webhook sia stato ricevuto, nella cronologia di GitHub o GitLab.
Il webhook non riesce con un errore di certificato
Se il pannello Plesk usa un certificato autofirmato, la connessione HTTPS può non riuscire. Plesk consiglia in questo caso di usare http:// all'inizio dell'URL del webhook. Poiché l'URL viaggia poi senza cifratura, ricorri a questa soluzione solo temporaneamente e segnala il problema al supporto.
GitLab indica che il webhook è disattivato
GitLab disattiva temporaneamente un webhook dopo quattro errori consecutivi, poi definitivamente dopo quaranta. Correggi la causa, poi invia un test riuscito per riattivarlo.
Alcuni file sono scomparsi dal sito
Un file eliminato dal repository viene eliminato anche dal sito durante il deploy. Conserva i file caricati dai tuoi utenti in una cartella non versionata e ripristina i file persi da un backup.
La directory di destinazione viene rifiutata
Due repository di uno stesso dominio non possono condividere la stessa cartella di deploy. Scegli un'altra Directory di destinazione.
Continua a essere visualizzata la vecchia pagina
Un file index.html può avere la precedenza sul tuo index.php, in particolare la pagina creata per impostazione predefinita da Plesk. Eliminalo da httpdocs se non fa parte del tuo progetto, poi svuota la cache del browser.
npm: command not found nelle azioni di deploy
Il percorso degli strumenti non viene caricato in questo contesto. Aggiungi la riga export PATH=/opt/plesk/node/24/bin:$PATH adattando la versione. Se l'errore persiste, probabilmente l'ambiente è in chroot.