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.
Een repository verbinden
- Kies je Provider: GitHub, GitLab of Bitbucket.
- Voer de Repository-URL in. De SSH-vorm is wat je wilt, bijvoorbeeld
git@github.com:user/repo.git. - Stel de Branch in waarvan wordt gedeployed. Het veld begint op
main. - Stel optioneel een Build-opdracht in, bijvoorbeeld
npm run build. - Stel optioneel een Uitvoermap in, bijvoorbeeld
dist,public, of.voor een repository die al gebouwd is. - 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.
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.
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 voegt een URL per PR toe bovenop deze setup.
- App-secrets opslaan voor een site voor de inloggegevens die je build en runtime nodig hebben.
- Site-activiteitenlogboek registreert configuratiewijzigingen die hier zijn gemaakt.