Git Deploy collega un repository a un sito, così che ogni push verso il branch scelto clona il codice, esegue la build e pubblica il risultato. Questa guida copre la connessione iniziale, i due passaggi lato repository che completano la configurazione, la lettura della cronologia delle distribuzioni e il rilevamento del buildpack che decide come viene costruita un'app Node.js.
Dove si Trova Git Deploy
Apri Siti web, fai clic sul sito, apri il gruppo Environment nel menu a sinistra del sito e scegli Deploy Git. Nelle vicinanze si trovano due pagine correlate:
- Deploy, la cronologia completa delle distribuzioni per questo sito, nello stesso gruppo Environment.
- Buildpack, la strategia di build rilevata, sui siti Node.js, nel gruppo App.
La pagina Git Deploy si descrive chiaramente: collega un repository e ogni push verso il branch configurato avvia una build e una distribuzione.
Connessione di un Repository
- Scegli il tuo Provider: GitHub, GitLab o Bitbucket.
- Inserisci l'URL repository. La forma SSH è quella che vuoi, per esempio
git@github.com:user/repo.git. - Imposta il Branch da cui distribuire. Il campo parte da
main. - Facoltativamente imposta un Comando di build, per esempio
npm run build. - Facoltativamente imposta una Directory output, per esempio
dist,public, oppure.per un repository già compilato. - Fai clic su Connetti repo.
Lascia vuoti il comando di build e la directory output se il tuo repository è già distribuibile così com'è, il che è il caso comune per un sito PHP o statico semplice.
Script Avanzati
Espandendo Avanzate vengono rivelati due campi aggiuntivi:
- Script di pre-distribuzione, che viene eseguito prima della build.
- Script di post-distribuzione, che viene eseguito dopo la distribuzione.
Usa l'hook di post-distribuzione per le cose che devono avvenire una volta che il nuovo codice è in atto: svuotare una cache applicativa, eseguire una migrazione del database, riavviare un worker.
Distribuzione Automatica al Push
Il toggle in fondo alla scheda controlla se i push distribuiscono o meno. Quando è attivo, ogni push verso il branch configurato avvia una distribuzione. Quando è disattivo, le distribuzioni vengono eseguite solo quando le avvii manualmente con Distribuisci ora.
Disattiva la distribuzione automatica durante un blocco del codice o un incidente, piuttosto che scollegare il repository. Scollegare elimina la chiave di distribuzione e il segreto del webhook, per cui dovrai rifare entrambi i passaggi lato repository in seguito.
Completare la Configurazione nel Tuo Repository
Collegare il repository in KPanel è solo il primo di tre passaggi. Finché non è stata eseguita una distribuzione, la pagina mostra un banner con la scritta Completa configurazione: 2 passaggi rimanenti con tutto ciò di cui hai bisogno.
Passaggio 2: Aggiungi la Chiave di Distribuzione
KapsuleHost ha bisogno di accesso in lettura per clonare il tuo repository. Il banner mostra una chiave pubblica con un pulsante Copia chiave.
Incollala nelle chiavi di distribuzione del tuo repository. Per GitHub il banner offre una scorciatoia Aggiungi a GitHub direttamente verso la pagina delle impostazioni corretta. L'accesso in lettura è sufficiente, non concedere la scrittura.
Passaggio 3: Aggiungi il Webhook
Il webhook è ciò che comunica a KapsuleHost che un push è avvenuto. Il banner fornisce tre valori:
| Campo | Valore |
|---|---|
| URL payload | Un URL che termina in /api/git-deploy/webhook/ più l'ID di questo sito |
| Secret | Un segreto di firma generato, nascosto finché non fai clic sull'icona a forma di occhio |
| Tipo di contenuto | application/json |
Copia ciascuno di questi valori nelle impostazioni webhook del tuo repository. Per GitHub è disponibile una scorciatoia Aggiungi webhook a GitHub. Imposta il tipo di contenuto su JSON, non sul predefinito con codifica a form, altrimenti il payload non verrà analizzato correttamente.
Tratta il segreto del webhook come una password. Chiunque lo possieda, insieme all'URL payload, può avviare una distribuzione del tuo sito. Entrambi i valori vengono mostrati solo a chi può già amministrare il sito, e il segreto resta nascosto dietro l'icona a forma di occhio finché non lo richiedi.
Distribuzione Manuale
Fai clic su Distribuisci ora nella pagina Git Deploy per compilare e distribuire la testa corrente del branch configurato senza effettuare il push di un commit. Funziona sia che la distribuzione automatica sia attiva o meno, ed è questo che lo rende lo strumento giusto durante un blocco: i push vengono ignorati, ma puoi comunque pubblicare la correzione.
Lettura della Cronologia delle Distribuzioni
Apri Environment, poi Deploy. La pagina si intitola Cronologia distribuzioni ed elenca ogni distribuzione avviata tramite webhook o manualmente, dalla più recente.
Ogni riga riporta:
- Un'icona di stato e lo SHA breve del commit, con il branch come etichetta.
- Il messaggio di commit, oppure Distribuzione manuale se non c'era alcun messaggio di commit da mostrare.
- L'autore, da quanto tempo è stata eseguita, quanto tempo ci ha impiegato e cosa l'ha attivata.
- Un'etichetta di stato.
Gli stati sono pending, building, deploying, success e failed. Finché qualcosa è in corso, la pagina si aggiorna automaticamente ogni cinque secondi e mostra una nota Aggiornamento automatico in corso sotto la tabella, così puoi lasciarla aperta e osservare l'arrivo di una distribuzione.
Quando una Distribuzione Fallisce
Una riga fallita riceve un pulsante Error sulla destra. Fai clic per espandere in linea l'output dell'errore catturato, senza lasciare la pagina. Quell'output è il testo di errore proprio della build, quindi di solito indica il file o il comando che è fallito.
Affrontalo in quest'ordine: leggi l'errore, riproduci lo stesso comando di build in locale, correggi, esegui il push. Se la build funziona in locale ma non qui, la differenza è quasi sempre legata all'ambiente, una dipendenza mancante che è installata globalmente sulla tua macchina, oppure un file presente nella tua directory di lavoro ma non committato.
Rilevamento del Buildpack
Sui siti Node.js, la pagina Buildpack nel gruppo App mostra come KapsuleHost ha deciso di costruire la tua app. Il rilevamento viene eseguito sui file alla radice del tuo repository, e la prima corrispondenza vince:
| Rilevato | Trigger |
|---|---|
| Buildpack personalizzato | kapsule.config.yaml o kapsule.config.yml alla radice |
| Buildpack Dockerfile | Dockerfile alla radice |
| Node.js | package.json con uno script start, build o dev |
| Python | requirements.txt o pyproject.toml |
| PHP | composer.json |
| Statico | index.html alla radice |
Se nulla corrisponde, la pagina lo segnala ed elenca i trigger supportati. Aggiungi un Dockerfile o un kapsule.config.yaml per prendere il controllo esplicito della build.
Esecuzione di una Build
Fai clic su Esegui build per metterne una in coda. La pagina effettua il polling ogni tre secondi mentre un'esecuzione è in corso, e la tabella Build recenti mostra le ultime esecuzioni con orario di inizio, tipo, stato, durata e riferimento dell'immagine risultante. Fai clic su una riga per vedere la coda del suo log.
Può essere in corso solo una build alla volta. Avviarne una seconda mentre una è in coda o in esecuzione viene rifiutato con Una compilazione è già in corso, il che è intenzionale: due build che scrivono lo stesso output contemporaneamente è il modo in cui si ottiene un sito distribuito a metà.
Scollegamento
Fai clic su Disconnect e conferma. La conferma è esplicita riguardo al raggio d'azione: la configurazione di Git Deploy e la chiave di distribuzione vengono rimosse, e i file del tuo sito non vengono interessati. Il sito continua a servire l'ultima versione distribuita.
Riordina in seguito eliminando la chiave di distribuzione e il webhook nelle impostazioni del tuo repository. Smetteranno semplicemente di funzionare, ma lasciare in giro voci inutilizzate rende più difficile il prossimo controllo.
Risoluzione dei Problemi
I push non attivano nulla. Controlla prima il toggle di distribuzione automatica, poi il webhook nel tuo repository. La maggior parte dei provider mostra le consegne recenti e i relativi codici di risposta, che ti dice immediatamente se la richiesta è uscita dal tuo repository.
La clonazione fallisce. La chiave di distribuzione manca, è stata incollata con un'interruzione di riga al suo interno, oppure è stata aggiunta al repository sbagliato. Copiala di nuovo con il pulsante Copia chiave piuttosto che selezionare il testo a mano.
La distribuzione ha successo ma il sito non cambia. La directory output è probabilmente sbagliata. Se la tua build scrive in dist e la directory output è vuota, i file compilati non raggiungono mai la radice servita.
Tutto dice pending e non si muove mai. La distribuzione è stata messa in coda ma non è mai stata presa in carico. Avvia una Distribuisci ora manuale e controlla la pagina Deploys per una riga di errore.
Dove Andare Ora
- Anteprime delle Distribuzioni per le Pull Request aggiunge un URL per ogni PR sopra questa configurazione.
- Memorizzazione dei Segreti dell'App per un Sito per le credenziali di cui la tua build e il runtime hanno bisogno.
- Registro Attività del Sito registra le modifiche di configurazione apportate qui.