Siti web
Distribuzione di un sito da Git
Git Deploy connects a repository to a site so that every push to your chosen branch clones the code, runs your build, and publishes the result. This guide covers the initial connection, the two…
Git Deploy connette un repository a un sito in modo che ogni push al ramo scelto clona il codice, esegue la build e pubblica il risultato. Questa guida copre la connessione iniziale, i due passaggi dal lato del repository che completano la configurazione, la lettura della cronologia dei deploy e il rilevamento buildpack che decide come viene compilata un'app Node.js.
Dove si trova Git Deploy
Apri Websites, fai clic sul sito, apri il menu Advanced nella barra delle schede del sito e scegli Git Deploy. Due pagine correlate si trovano nello stesso menu:
- Deploys, la cronologia completa dei deploy per questo sito.
- Buildpack, la strategia di build rilevata, sui siti Node.js.
La pagina Git Deploy si descrive chiaramente: connetti un repository e ogni push al ramo configurato attiva una build e un deploy.
Connessione di un Repository
- Scegli il tuo Provider: GitHub, GitLab o Bitbucket.
- Inserisci l'URL del repository. La forma SSH è quella che vuoi, ad esempio
git@github.com:user/repo.git. - Imposta il Branch da cui eseguire il deploy. Il campo inizia a
main. - Facoltativamente imposta un Build command, ad esempio
npm run build. - Facoltativamente imposta una Output directory, ad esempio
dist,publico.per un repository già compilato. - Fai clic su Connect repo.
Lascia vuoti il build command e la output directory se il tuo repository è già deployabile così com'è, il che è il caso comune per un sito PHP semplice o statico.
Script Avanzati
Espandendo Advanced si rivelano due campi aggiuntivi:
- Pre-deploy script, che viene eseguito prima della build.
- Post-deploy script, che viene eseguito dopo il deploy.
Utilizza l'hook post-deploy per le operazioni che devono accadere una volta che il nuovo codice è in posizione: cancellare una cache dell'applicazione, eseguire una migrazione del database, riavviare un worker.
Auto-Deploy al Push
L'interruttore in fondo alla scheda controlla se i push eseguono il deploy o meno. Quando è attivo, ogni push al ramo configurato attiva un deploy. Quando è disattivato, i deploy vengono eseguiti solo quando li attivi manualmente con Deploy now.
Disattiva il deploy automatico durante un blocco del codice o un incidente piuttosto che disconnettere il repository. Disconnettere elimina la deploy key e il webhook secret, quindi devi ripetere entrambi i passaggi dal lato del repository successivamente.
Completamento della Configurazione nel Tuo Repository
Connettere il repository in KPanel è solo il primo di tre passaggi. Finché non è stato eseguito un deploy, la pagina mostra un banner che legge Complete setup: 2 steps remaining con tutto ciò di cui hai bisogno.
Passaggio 2: Aggiungi la Deploy Key
Kapsule ha bisogno dell'accesso in lettura per clonare il tuo repository. Il banner mostra una chiave pubblica con un pulsante Copy key.
Incollala nelle deploy keys del tuo repository. Per GitHub il banner offre un collegamento Add to GitHub direttamente alla pagina delle impostazioni corrette. L'accesso in lettura è sufficiente; non concedere accesso in scrittura.
Passaggio 3: Aggiungi il Webhook
Il webhook è ciò che comunica a Kapsule che è avvenuto un push. Il banner ti fornisce tre valori:
| Campo | Valore |
|---|---|
| Payload URL | Un URL che termina in /api/git-deploy/webhook/ più l'ID di questo sito |
| Secret | Un secret di firma generato, nascosto finché non fai clic sull'icona dell'occhio |
| Content Type | application/json |
Copia ciascuno nelle impostazioni del webhook del tuo repository. Per GitHub c'è un collegamento Add webhook to GitHub. Imposta il content type su JSON, non sul default codificato in forma, altrimenti il payload non verrà analizzato.
Tratta il webhook secret come una password. Chiunque lo possieda, più l'URL del payload, può attivare un deploy del tuo sito. Entrambi i valori vengono mostrati solo alle persone che possono già amministrare il sito e il secret rimane nascosto dietro l'icona dell'occhio finché non lo richiedi.
Deploy Manuale
Fai clic su Deploy now sulla pagina Git Deploy per compilare e distribuire l'HEAD attuale del ramo configurato senza eseguire il push di un commit. Questo funziona indipendentemente dal fatto che il deploy automatico sia attivo, il che lo rende lo strumento giusto durante un blocco: i push vengono ignorati, ma puoi comunque distribuire la correzione.
Lettura della Cronologia dei Deploy
Apri Advanced, quindi Deploys. La pagina è intitolata Deploy history ed elenca ogni distribuzione attivata da webhook o manualmente, con la più recente per prima.
Ogni riga contiene:
- Un'icona di stato e lo SHA del commit breve, con il ramo come pillow.
- Il messaggio di commit o Manual deploy se non c'era un messaggio di commit da mostrare.
- L'autore, quanto tempo fa è stato eseguito, quanto tempo ha impiegato e cosa lo ha attivato.
- Una pillow di stato.
Gli stati sono pending, building, deploying, success e failed. Mentre qualcosa è in volo, la pagina si aggiorna ogni cinque secondi e mostra una nota Refreshing automatically sotto la tabella, quindi puoi lasciarla aperta e osservare un deploy in arrivo.
Quando un Deploy Fallisce
Una riga non riuscita ottiene un pulsante Error a destra. Fai clic su di esso per espandere l'output di errore acquisito in linea, senza lasciare la pagina. Quell'output è il testo di errore della build stessa, quindi di solito nomina il file o il comando che ha fallito.
Elaboralo in questo ordine: leggi l'errore, riproduci lo stesso build command localmente, correggi, esegui il push. Se la build funziona localmente ma non qui, la differenza è quasi sempre un'ambiente, una dipendenza mancante che è installata globalmente sulla tua macchina, o un file che è nella tua directory di lavoro ma non sottoposto a commit.
Rilevamento Buildpack
Sui siti Node.js, la pagina Buildpack nel menu Advanced mostra come Kapsule ha deciso di compilare la tua app. Il rilevamento viene eseguito sui file nella radice del tuo repository e la prima corrispondenza vince:
| Rilevato | Trigger |
|---|---|
| Custom buildpack | kapsule.config.yaml o kapsule.config.yml alla radice |
| Dockerfile buildpack | Dockerfile alla radice |
| Node.js | package.json con uno script start, build o dev |
| Python | requirements.txt o pyproject.toml |
| PHP | composer.json |
| Static | index.html alla radice |
Se nulla corrisponde, la pagina lo dice e elenca i trigger supportati. Aggiungi un Dockerfile o un kapsule.config.yaml per prendere il controllo della build in modo esplicito.
Esecuzione di una Build
Fai clic su Run build per metterne una in coda. La pagina esegue il polling ogni tre secondi mentre una esecuzione è in corso e la tabella Recent builds mostra le ultime esecuzioni con la loro ora di inizio, tipo, stato, durata e il riferimento dell'immagine risultante. Fai clic su una riga per vedere la coda del suo log.
Solo una build può essere in volo alla volta. L'attivazione di una seconda mentre una è in coda o in esecuzione viene rifiutata con A build is already in progress, il che è intenzionale: due build che scrivono nello stesso output contemporaneamente è come si ottiene un sito semi-distribuito.
Disconnessione
Fai clic su Disconnect e conferma. La conferma è esplicita sulla portata dell'impatto: la configurazione di Git deploy e la deploy key vengono rimosse e i file del tuo sito non sono interessati. Il sito continua a servire tutto ciò che è stato distribuito per ultimo.
Pulisci dopo eliminando la deploy key e il webhook nelle impostazioni del tuo repository. Smetteranno semplicemente di funzionare, ma lasciare voci morte in giro rende più difficile il prossimo audit.
Risoluzione dei Problemi
I push non attivano nulla. Controlla prima l'interruttore di deploy automatico, quindi il webhook nel tuo repository. La maggior parte dei provider mostra le consegne recenti e i loro codici di risposta, il che ti dice immediatamente se la richiesta ha lasciato il tuo repository.
La clonazione fallisce. La deploy key è mancante, è stata incollata con un'interruzione di riga, o è stata aggiunta al repository sbagliato. Copia di nuovo con il pulsante Copy key piuttosto che selezionare il testo a mano.
Il deploy riesce ma il sito non cambia. La output directory è probabilmente sbagliata. Se la tua build scrive in dist e la output directory è vuota, i file compilati non raggiungono mai la radice servita.
Tutto dice pending e non si muove mai. Il deploy è stato messo in coda ma mai ritirato. Attiva un Deploy now manuale e controlla la pagina Deploys per una riga di errore.
Dove Andare Dopo
- Preview Deploys Per Pull Requests aggiunge un URL per PR in aggiunta a questa configurazione.
- Memorizzazione di Segreti dell'App per un Sito per le credenziali di cui la tua build e runtime hanno bisogno.
- Site Activity Log registra le modifiche di configurazione effettuate qui.