Deployen met Git

Een website die uit een Git-repository komt, zet je niet meer over met FTP. Je haalt de repository één keer binnen, en daarna is publiceren één knop: de server maakt een kopie van precies één commit, zet die klaar in een eigen map, en laat de website daarnaar wijzen. Bevalt het niet, dan gaat de website met één knop weer terug naar de vorige versie. Er wordt daarbij geen bestand verplaatst — alleen een snelkoppeling verzet.

Je vindt het op Accounts → je account → Git. Staat die tab er niet, dan kijk je met een account dat er niet bij mag: het is een tabblad voor hostingpartijen en beheerders, niet voor de eindklant.

Waarom er twee mappen zijn

Bij een klassieke opzet staat je code in de map die de webserver toont. Bij deze opzet staan er twee dingen naast elkaar:

• de werkkopie — de repository zelf, standaard in repos/<naam>. Hier staat de .git-map, hier haal je nieuwe commits binnen.
• de releasemap — standaard deploys/<naam>. Daaronder staat een map releases/ met per publicatie één map, en een snelkoppeling current die naar de release wijst die live staat.

De documentmap van je website zet je op die snelkoppeling. Daarom is publiceren zo goedkoop: de nieuwe release wordt eerst helemaal uitgepakt en pas als dat gelukt is verspringt de snelkoppeling. Gaat er iets mis tijdens het uitpakken, dan heeft je bezoeker daar niets van gemerkt.

De release bevat nooit een .git-map. Dat is met opzet: een .git onder een documentmap betekent dat iedereen met een browser je hele geschiedenis kan downloaden, inclusief wat er ooit per ongeluk in een commit is beland.

Een privé-repository binnenhalen

Voor een openbare repository is een https://-URL genoeg. Voor een privé- repository maak je eerst een deploysleutel:

1. Git → ⋯ → Deploysleutel maken, geef hem een naam (bijvoorbeeld de provider waar hij bij hoort).
2. Kopieer de publieke sleutel die je krijgt en plak hem bij GitHub, GitLab of Gitea onder Deploy keys van díe repository. Alleen-lezen is genoeg.
3. Repository klonen, vul de ssh://- of git@host:pad-URL in en kies de sleutel die je net gemaakt hebt.

De privéhelft van die sleutel blijft op de server staan, met rechten 0600, en komt nooit in een antwoord of in een log terecht. Hij geeft ook geen toegang tót de server: hij staat niet bij de inlogsleutels van het account.

De lijst met sleutels lezen

Onder Git → Sleutels staat één kaart per sleutel, en daar staat alles op waarmee je hem kunt herkennen: de naam die je hem gaf, zijn vingerafdruk (SHA256:…, met soort en lengte erbij), of de privéhelft nog op de server staat, en welke repository's hem gebruiken. Staat er dat geen enkele hem gebruikt, dan is dat geen fout — dat is de normale toestand van een sleutel die je zojuist hebt aangemaakt en nog nergens hebt gekozen.

De vingerafdruk staat er voluit en niet afgekort. Dat is met opzet: hij is er om te vergelijken met wat je provider bij Deploy keys laat zien, en een halve vingerafdruk vergelijkt met niets. Op een telefoon breekt hij over meerdere regels binnen zijn kaart — sinds ronde 5, want daarvóór duwde hij het scherm opzij.

Wat je nooit ziet, en niemand anders ook, is de privéhelft. "Sleutel vervangen" maakt een nieuw paar; de oude publieke sleutel bij je provider werkt daarna niet meer, en die moet je daar dus vervangen door de nieuwe.

Op de commandoregel is het hetzelfde in twee opdrachten:

corectl git key add github --account demo
corectl git clone site --account demo \
  --remote git@github.com:jouwteam/site.git --key github

Wat CoreCP weigert te klonen is een korte lijst, en elke regel heeft een reden: ext::… (dat voert een commando uit in plaats van iets op te halen), file:// en een pad op de server zelf (daar is het bestandsbeheer voor), git:// (geen versleuteling en geen controle op wat je terugkrijgt) en een URL met een wachtwoord erin (dat zou in leesbare vorm op de server komen te staan — gebruik een deploysleutel).

Publiceren en terugzetten

Kies in het scherm Releasemap instellen, vul de map in (deploys/site is prima), kies welke branch of tag gepubliceerd wordt en hoeveel releases je wilt bewaren — minimaal twee, want de vorige release ís de weg terug. Zet daarna de documentmap van je website op deploys/site/current; dat doe je op het websitescherm onder Documentmap.

Vanaf dat moment is publiceren één knop. Publiceren haalt eerst de nieuwste commits op, pakt de gekozen branch uit in een nieuwe release en verzet de snelkoppeling. Bovenaan het scherm staat de hele tijd welke release live staat, uit welke commit hij komt en wanneer hij geplaatst is.

Terug naar vorige doet precies het omgekeerde: de snelkoppeling gaat terug naar de release ervoor. De release waar je vandaan komt blijft gewoon staan, dus je kunt net zo makkelijk weer vooruit. In de lijst met releases kun je ook een specifieke oudere release aanwijzen. Een release die al opgeruimd is — omdat je er meer gepubliceerd hebt dan je bewaart — staat er nog wel bij, maar met de melding opgeruimd en zonder knop: die is echt van de schijf.

Wat er gebeurt als het misgaat

• De remote antwoordt niet. Er wordt niets gepubliceerd en je website blijft tonen wat hij toonde. De melding bevat wat git zelf zei.
• De branch bestaat niet. Hetzelfde: de fout komt vóór het uitpakken.
• Het uitpakken loopt vast. De halve release wordt opgeruimd en de snelkoppeling is niet verzet.
• Je hebt lokaal iets gewijzigd op de server. Bijwerken weigert dan; je ziet welke bestanden het zijn. Wil je die wijzigingen kwijt, dan is dat een aparte, expliciete handeling.

Publiceren is altijd veilig te herhalen: er wordt nooit in een bestaande release geschreven, elke publicatie maakt een nieuwe map ernaast.

Een privé-repository over https

Niet elke provider biedt deploysleutels, en niet elk netwerk laat SSH naar buiten. Sla in dat geval een toegangstoken op:

1. Maak het token bij je provider. Bij GitHub is dat een fine-grained personal access token met leesrecht op de repository, bij GitLab een project- of deploytoken, bij Gitea een token op je eigen account.
2. Git → ⋯ → Token opslaan. Geef het een naam, vul in voor welke server het geldt (github.com, gitlab.com, je eigen adres), met welke gebruikersnaam het meegaat, en plak het token.
3. Repository klonen, vul de https://-URL in en kies het token.

Over die gebruikersnaam: providers zijn het er niet over eens, dus CoreCP vraagt het in plaats van te gokken. GitHub accepteert elk woord naast een token, GitLab wil oauth2, Gitea wil je login. De documentatie van je provider zegt welke.

Het token wordt met rechten 0600 op de server opgeslagen en daarna nooit meer getoond — niet op een scherm, niet in een antwoord, niet in een logregel. Raak je het kwijt, maak dan een nieuw token bij je provider en sla dat op; hier valt niets terug te halen. Het is ook vastgezet op de server die je noemde: een token voor github.com gaat nooit naar een andere server, ook niet als het adres van de repository later verandert.

Een repository gebruikt een deploysleutel of een token, niet allebei. Het adres bepaalt welke: ssh:// en git@host:pad vragen om de sleutel, https:// om het token.

corectl git token add github --account demo --host github.com --username deploy
corectl git clone site --account demo \
  --remote https://github.com/jouwteam/site.git --token github

Automatisch publiceren na een push

In plaats van zelf op Publiceren te drukken kun je je provider laten melden dat er gepusht is.

1. Git → ⋯ → Adres aanmaken. Kies de repository en de branch die gepubliceerd moet worden.
2. Je krijgt een adres en een geheim, allebei één keer. Kopieer ze.
3. Voeg bij je provider een webhook toe: plak het adres in het URL-veld en het geheim in het veld Secret (GitHub) of Secret token (GitLab). Content type JSON, en het push-event is het enige dat telt.

Vanaf dat moment publiceert een push naar die branch een nieuwe release, precies zoals de knop dat doet. Al het andere dat je provider stuurt — een push naar een andere branch, een tag, een pull request, de testmelding die hij verstuurt als je de webhook opslaat — wordt ontvangen, opgeschreven en doet niets.

Het geheim is wat bewijst dat de melding van jouw provider komt en niet van iemand die het adres heeft geraden. Zonder kloppend geheim wordt de melding geweigerd, en ook die weigering wordt opgeschreven: aan die regel zie je dat er iemand aanklopt. Raak je het geheim kwijt, verwijder dan het adres en maak een nieuw aan — opzoeken kan niet.

Dezelfde push die twee keer bezorgd wordt publiceert één keer. Dat geldt of je provider het na een time-out opnieuw probeerde, of je zelf op opnieuw bezorgen drukte, of iemand een melding herhaalde die hij eerder had gezien: CoreCP herkent de melding zelf, niet het label dat je provider eraan hing.

Staat er mislukt bij een melding, dan kon jouw server op dat moment niet om een publicatie gevraagd worden — bijvoorbeeld omdat de repository niet meer onder beheer staat. Niemand probeert dat vanzelf opnieuw: CoreCP niet, en je provider ook niet. Los op wat er in de regel staat en druk bij je provider op opnieuw bezorgen.

Logboek op het adres toont de laatste honderd meldingen, nieuwste eerst, met wat elk van ze deed: gepubliceerd, niets gedaan, al eerder verwerkt, geweigerd of mislukt. Die lijst is het antwoord op "waarom veranderde de site om drie uur 's nachts", en net zo vaak op "waarom juist niet".

Uitzetten houdt het adres en laat het niets meer publiceren — handig terwijl je aan iets werkt. Je provider blijft doorsturen; de meldingen komen binnen, worden opgeschreven en worden geweigerd.

Een branch beschermen

Op het scherm van een repository geef je aan op welke branches dit paneel weigert werk weg te gooien. Op een beschermde branch worden Serverversie ophalen en wijzigingen weggooien en omschakelen geweigerd, en kan de werkkopie van de repository niet verwijderd worden zolang de bescherming erop staat.

Het is een handrem tegen een misklik, geen slot. Alles hier draait als jouw hostingaccount in zijn eigen home, dus wie SSH-toegang tot dat account heeft kan het met de hand alsnog. Het paneel zegt dat op het scherm in plaats van je iets anders te laten geloven.

Als jouw kopie en de server uiteenlopen

Bijwerken is een fast-forward of een weigering — er blijft nooit een halve merge in je home achter. Staan er commits op de server die er bij je provider niet zijn en andersom, dan zegt het paneel dat de twee uiteen zijn gaan lopen en biedt het drie dingen aan.

Laat zien wat er uiteenloopt toont hoeveel commits er aan elke kant zijn en — nuttiger — aan welke bestanden van beide kanten is gewerkt. Die korte lijst is waar een verzoening werkelijk over zou gaan.

Werk bewaren onder een naam maakt een branch die naar de commits wijst die alleen op deze server staan. Er gaat niets weg, en het werk blijft daarna bereikbaar in de historie en in de verschillen.

Serverversie ophalen gooit elke commit weg die alleen hier staat, samen met wijzigingen die nog niet zijn vastgelegd. Bestanden die je hebt toegevoegd zonder ze aan Git te melden blijven staan.

De volgorde is het advies: eerst bewaren, dan ophalen. Dat maakt van een verlies een keuze.

Wat dit niet doet

Committen, mergen en pushen vanuit het paneel zitten er bewust niet in, en een editor in de browser evenmin. Een commit samenstellen vraagt om een plek om te schrijven en een merge oplossen om een plek om beide kanten te lezen — een hostingpaneel is voor allebei een slechte plek. Wat dit paneel wél doet: een repository op de server krijgen, er precies één commit uit publiceren, de vorige terugzetten, en helder uitleggen wat er in de weg staat als dat niet kan.