# Distribuire un Sito da Git

Source: https://support.kapsulehost.com/it-it/site-git-deploy

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.

![La pagina Git Deploy per un sito in KPanel, dove un repository è collegato](https://support.kapsulehost.com/help/screenshots/site-git-deploy.4716f1a9.webp)

## Connessione di un Repository

1. Scegli il tuo **Provider**: GitHub, GitLab o Bitbucket.
2. Inserisci l'**URL repository**. La forma SSH è quella che vuoi, per esempio `git@github.com:user/repo.git`.
3. Imposta il **Branch** da cui distribuire. Il campo parte da `main`.
4. Facoltativamente imposta un **Comando di build**, per esempio `npm run build`.
5. Facoltativamente imposta una **Directory output**, per esempio `dist`, `public`, oppure `.` per un repository già compilato.
6. 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**.

> **Tip:** 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.

> **Warning:** 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](https://support.kapsulehost.com/it-it/site-preview) aggiunge un URL per ogni PR sopra questa configurazione.
- [Memorizzazione dei Segreti dell'App per un Sito](https://support.kapsulehost.com/it-it/site-secrets) per le credenziali di cui la tua build e il runtime hanno bisogno.
- [Registro Attività del Sito](https://support.kapsulehost.com/it-it/site-activity-log) registra le modifiche di configurazione apportate qui.