# Een site deployen vanuit Git

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

Git Deploy koppelt een repository aan een site, zodat elke push naar je gekozen branch de code kloont, je build uitvoert en het resultaat publiceert. Deze handleiding behandelt de eerste koppeling, de twee stappen aan de kant van de repository die de setup afronden, het lezen van de deploy-geschiedenis en de buildpack-detectie die bepaalt hoe een Node.js-app wordt gebouwd.

## Waar Git Deploy zich bevindt

Open **Websites**, klik op de site, open de groep **Environment** in het linkermenu van de site en kies **Git-deploy**. Twee gerelateerde pagina's bevinden zich in de buurt:

- **Implementaties**, de volledige deploy-geschiedenis voor deze site, in dezelfde groep **Environment**.
- **Buildpack**, de gedetecteerde buildstrategie, op Node.js-sites, in de groep **Apps**.

De Git Deploy-pagina beschrijft zichzelf duidelijk: verbind een repository en elke push naar je geconfigureerde branch activeert een build en deployment.

![De Git Deploy-pagina voor een site in KPanel, waar een repository is verbonden](https://support.kapsulehost.com/help/screenshots/site-git-deploy.4716f1a9.webp)

## Een repository verbinden

1. Kies je **Provider**: GitHub, GitLab of Bitbucket.
2. Voer de **Repository-URL** in. De SSH-vorm is wat je wilt, bijvoorbeeld `git@github.com:user/repo.git`.
3. Stel de **Branch** in waarvan wordt gedeployed. Het veld begint op `main`.
4. Stel optioneel een **Build-opdracht** in, bijvoorbeeld `npm run build`.
5. Stel optioneel een **Uitvoermap** in, bijvoorbeeld `dist`, `public`, of `.` voor een repository die al gebouwd is.
6. Klik op **Repository verbinden**.

Laat de build-opdracht en uitvoermap leeg als je repository al deploybaar is zoals die is, wat het gebruikelijke geval is voor een gewone PHP- of statische site.

### Geavanceerde scripts

Als je **Geavanceerd** uitklapt, verschijnen er twee extra velden:

- **Pre-deployscript**, dat wordt uitgevoerd vóór de build.
- **Post-deployscript**, dat wordt uitgevoerd na de deployment.

Gebruik de post-deployhook voor de dingen die moeten gebeuren zodra nieuwe code aanwezig is: het leegmaken van een applicatiecache, het uitvoeren van een databasemigratie, het herstarten van een worker.

### Automatisch deployen bij push

De schakelaar onderaan de kaart bepaalt of pushes überhaupt deployen. Wanneer deze aanstaat, activeert elke push naar de geconfigureerde branch een deployment. Wanneer deze uitstaat, worden deployments alleen uitgevoerd wanneer je ze handmatig activeert met **Nu implementeren**.

> **Tip:** Zet automatisch deployen uit tijdens een codefreeze of een incident, in plaats van de repository los te koppelen. Loskoppelen gooit de deploysleutel en het webhook-geheim weg, zodat je beide stappen aan de kant van de repository daarna opnieuw moet doen.

## De setup afronden in je repository

Het verbinden van de repository in KPanel is pas de eerste van drie stappen. Totdat er een deployment is uitgevoerd, toont de pagina een banner met de tekst **Setup voltooien: 2 stappen resterend** met alles wat je nodig hebt.

### Stap 2: de deploysleutel toevoegen

KapsuleHost heeft leestoegang nodig om je repository te klonen. De banner toont een publieke sleutel met een knop **Token kopiëren**.

Plak deze in de deploysleutels van je repository. Voor GitHub biedt de banner een snelkoppeling **Toevoegen aan GitHub** rechtstreeks naar de juiste instellingenpagina. Leestoegang is voldoende; geef geen schrijftoegang.

### Stap 3: de webhook toevoegen

De webhook is wat KapsuleHost laat weten dat er een push heeft plaatsgevonden. De banner geeft je drie waarden:

| Veld | Waarde |
|---|---|
| Payload-URL | Een URL die eindigt op `/api/git-deploy/webhook/` plus het ID van deze site |
| Secret | Een gegenereerd ondertekeningsgeheim, verborgen totdat je op het oogicoon klikt |
| Inhoudstype | `application/json` |

Kopieer elke waarde naar de webhookinstellingen van je repository. Voor GitHub is er een snelkoppeling **Webhook toevoegen aan GitHub**. Stel het inhoudstype in op JSON, niet op de standaard form-encoded optie, anders kan de payload niet worden verwerkt.

> **Warning:** Behandel het webhook-geheim als een wachtwoord. Iedereen die dit bezit, samen met de payload-URL, kan een deployment van je site activeren. Beide waarden worden alleen getoond aan mensen die de site al kunnen beheren, en het geheim blijft verborgen achter het oogicoon totdat je erom vraagt.

## Handmatig deployen

Klik op **Nu implementeren** op de Git Deploy-pagina om de huidige head van de geconfigureerde branch te bouwen en te deployen zonder een commit te pushen. Dit werkt ongeacht of automatisch deployen aanstaat, wat het de juiste tool maakt tijdens een freeze: pushes worden genegeerd, maar je kunt nog steeds de fix uitbrengen.

## De deploy-geschiedenis lezen

Open **Environment**, dan **Implementaties**. De pagina heet **Deploy-geschiedenis** en toont elke deployment die is geactiveerd via webhook of handmatig, nieuwste eerst.

Elke rij bevat:

- Een statusicoon en de korte commit-SHA, met de branch als pil.
- Het commitbericht, of **Handmatige deployment** als er geen commitbericht was om te tonen.
- De auteur, hoe lang geleden deze is uitgevoerd, hoe lang het duurde, en wat de trigger was.
- Een statuspil.

De statussen zijn **pending**, **building**, **deploying**, **success** en **failed**. Zolang er iets in uitvoering is, ververst de pagina zichzelf elke vijf seconden en toont een notitie **Refreshing automatically** onder de tabel, zodat je de pagina open kunt laten staan en een deployment kunt zien landen.

### Wanneer een deployment mislukt

Een mislukte rij krijgt rechts een knop **Error**. Klik erop om de vastgelegde foutuitvoer inline uit te klappen, zonder de pagina te verlaten. Die uitvoer is de eigen foutmelding van de build, dus die noemt meestal het bestand of de opdracht die faalde.

Werk het in deze volgorde uit: lees de fout, reproduceer dezelfde build-opdracht lokaal, los op, push. Als de build lokaal werkt maar hier niet, is het verschil bijna altijd een omgevingsverschil: een afhankelijkheid die globaal op je machine is geïnstalleerd, of een bestand dat in je werkmap staat maar niet is gecommit.

## Buildpack-detectie

Op Node.js-sites toont de pagina **Buildpack** in de groep **Apps** hoe KapsuleHost heeft besloten je app te bouwen. Detectie wordt uitgevoerd over de bestanden in de root van je repository, en de eerste match wint:

| Gedetecteerd | Trigger |
|---|---|
| Aangepaste buildpack | `kapsule.config.yaml` of `kapsule.config.yml` in de root |
| Dockerfile-buildpack | `Dockerfile` in de root |
| Node.js | `package.json` met een `start`, `build` of `dev` script |
| Python | `requirements.txt` of `pyproject.toml` |
| PHP | `composer.json` |
| Statisch | `index.html` in de root |

Als er niets overeenkomt, meldt de pagina dit en toont de ondersteunde triggers. Voeg een `Dockerfile` of een `kapsule.config.yaml` toe om expliciet de controle over de build over te nemen.

### Een build uitvoeren

Klik op **Build uitvoeren** om er een in de wachtrij te zetten. De pagina vraagt elke drie seconden een update op terwijl een run bezig is, en de tabel **Recente builds** toont de laatste runs met hun starttijd, type, status, duur en resulterende imagereferentie. Klik op een rij om de staart van het log te bekijken.

Er kan maar één build tegelijk actief zijn. Het activeren van een tweede terwijl er een in de wachtrij staat of actief is, wordt geweigerd met **Een build is al bezig**, wat opzettelijk is: twee builds die tegelijk dezelfde uitvoer schrijven, is hoe je een halfgedeployde site krijgt.

## Loskoppelen

Klik op **Disconnect** en bevestig. De bevestiging is expliciet over de impact: de Git-deployconfiguratie en de deploysleutel worden verwijderd, en je sitebestanden worden niet beïnvloed. De site blijft tonen wat als laatste werd gedeployed.

Ruim daarna op door de deploysleutel en de webhook in je repository-instellingen te verwijderen. Ze zullen gewoon stoppen met werken, maar het achterlaten van dode items maakt de volgende audit lastiger.

## Probleemoplossing

**Pushes activeren niets.** Controleer eerst de schakelaar voor automatisch deployen, en dan de webhook in je repository. De meeste providers tonen recente aflevering en hun responscodes, wat je direct vertelt of het verzoek je repository überhaupt heeft verlaten.

**Klonen mislukt.** De deploysleutel ontbreekt, is geplakt met een regeleinde erin, of is toegevoegd aan de verkeerde repository. Kopieer deze opnieuw met de knop **Token kopiëren** in plaats van de tekst handmatig te selecteren.

**De deployment slaagt maar de site verandert niet.** De uitvoermap is waarschijnlijk verkeerd. Als je build naar `dist` schrijft en de uitvoermap leeg is, bereiken de gebouwde bestanden nooit de bediende root.

**Alles zegt pending en beweegt nooit.** De deployment stond in de wachtrij maar is nooit opgepakt. Activeer een handmatige **Nu implementeren** en controleer de pagina Deploys op een foutrij.

## Waar te beginnen

- [Preview-deployments voor pull requests](https://support.kapsulehost.com/nl-nl/site-preview) voegt een URL per PR toe bovenop deze setup.
- [App-secrets opslaan voor een site](https://support.kapsulehost.com/nl-nl/site-secrets) voor de inloggegevens die je build en runtime nodig hebben.
- [Site-activiteitenlogboek](https://support.kapsulehost.com/nl-nl/site-activity-log) registreert configuratiewijzigingen die hier zijn gemaakt.