Verbindung zu einem GitLab-Repository herstellen

GitLab connects to Orbit through OAuth rather than an installed app: you authorise Kapsule once, Orbit lists the projects your GitLab account can reach, and it registers a webhook per repository so…

GitLab-Repo verbinden

GitLab verbindet sich mit Orbit über OAuth statt über eine installierte App: Sie autorisieren Kapsule einmalig, Orbit listet die Projekte auf, auf die Ihr GitLab-Konto zugreifen kann, und registriert einen Webhook pro Repository, sodass jeder Push einen Build auslöst. Dieser Leitfaden behandelt die Verbindung, die Auswahl eines Repositories, die Gating von Deployments in Ihrer GitLab-Pipeline und die üblichen Gründe, warum ein Repository nicht angezeigt wird.

Vorbereitung

Orbit kann nur GitLab-Projekte sehen, die Ihr eigenes Konto sehen kann. Für ein gruppeneigenes Projekt benötigen Sie mindestens Developer-Zugriff, und Sie benötigen ausreichend Berechtigung, um einen Webhook im Repository zu erstellen. Wenn Ihre GitLab-Instanz ausgehende Webhooks einschränkt, gilt diese Einschränkung auch hier.

Schritt 1: GitLab verbinden

Klicken Sie in KPanel auf Orbit in der linken Seitenleiste.
Klicken Sie auf New project.
Lassen Sie den Modus auf Import Git Repo eingestellt.
Klicken Sie in Schritt 1 auf Connect GitLab.

Sie werden zu GitLab weitergeleitet, um die Kapsule Orbit-Anwendung zu autorisieren. Genehmigen Sie die angeforderten Bereiche, und GitLab leitet Sie mit Ihren geladenen Repositories zu KPanel zurück. Schritt 1 zeigt dann Just connected an.

Wenn die Verbindung fehlschlägt, zeigt KPanel den von GitLab zurückgegebenen Fehler statt einer generischen Nachricht an. Lesen Sie ihn, bevor Sie es erneut versuchen: Eine Bereichsverweigerung und eine abgelaufene Autorisierung benötigen unterschiedliche Lösungen.

Schritt 2: Wählen Sie ein Repository

Ihre zugänglichen Repositories werden als Liste angezeigt. Klicken Sie neben dem gewünschten auf Select. Private Repositories tragen ein Private-Badge; Orbit stellt öffentliche und private Repositories gleichermaßen bereit.

Wenn ein Repository fehlt

Überprüfen Sie Ihre Rolle im Projekt. Reporter-Zugriff ist nicht ausreichend; Sie benötigen mindestens Developer.
Wenn das Projekt einer Gruppe angehört, bestätigen Sie, dass Ihre Mitgliedschaft in der Gruppe oder im Projekt selbst ist, nicht nur in einer übergeordneten Gruppe mit einer eingeschränkten Rolle.
Klicken Sie auf Reconnect GitLab in Schritt 1, um den OAuth-Flow erneut auszuführen. Dies aktualisiert das Token und liest Ihre Projektliste neu.

Wenn das Panel No repos accessible anzeigt, ist die OAuth-Berechtigung durchgegangen, hat aber nichts zurückgegeben. Verbinden Sie sich erneut und überprüfen Sie, dass Sie die Repository-Bereiche genehmigt haben, nicht einen reduzierten Satz.

Schritt 3: Konfigurieren Sie Ihr Projekt

Feld	Funktion
Project Name	Der Anzeigename in KPanel, zum Beispiel `my-app`
Deploy URL	Die Subdomain unter `kaps.run`, sodass `my-app` zu `my-app.kaps.run` wird

Klicken Sie auf Create project. Orbit klont das Repository, reiht den ersten Build ein und führt Sie zur Projektübersicht.

Der Deploy URL-Slug ist bei der Erstellung fest und kann später nicht geändert werden. Um unter einer anderen Adresse zu veröffentlichen, hängen Sie stattdessen eine benutzerdefinierte Domain an. Siehe Adding a Custom Domain to Your Project.

Automatische Deployments

Orbit registriert einen Webhook in Ihrem GitLab-Repository, wenn das Projekt erstellt wird. Danach:

Ein Push auf Ihren Production-Branch reiht ein Production-Deployment ein.
Ein Push auf einen anderen Branch erstellt eine isolierte Vorschau unter branch-<branch-name>.kaps.run, wenn Branch previews in Settings unter Runtime aktiviert ist. Siehe Branch Preview Deployments in Orbit.
Das Löschen eines Branches pausiert seine Vorschauumgebung, und der Speicher wird in etwa einem Tag freigegeben.

Sie erstellen oder verwalten den Webhook nicht von Hand.

Warten auf Ihre GitLab CI-Pipeline

Wenn Sie Tests in GitLab CI ausführen, kann Orbit das Deployment halten, bis die Pipeline erfolgreich ist.

Öffnen Sie das Projekt und dann Settings.
Suchen Sie CI required checks.
Geben Sie einen beliebigen Wert ein und speichern Sie.

Bei GitLab wird der Wert selbst nicht mit Jobnamen abgeglichen: Jeder beliebige Wert teilt Orbit mit, auf das gesamte Pipeline-Erfolg zu warten. Ein Pipeline-Fehler bricht das Orbit-Deployment automatisch ab. Dies gilt nur für Push-ausgelöste Deployments auf dem Production-Branch.

Hier unterscheiden sich die beiden Provider. GitHub gleicht den Wert mit benannten Actions-Jobs ab; GitLab behandelt jeden Wert als "auf die gesamte Pipeline warten". Wenn Sie Einstellungen zwischen einem GitHub- und einem GitLab-Projekt kopieren, erwarten Sie nicht, dass sich das gleiche Feld identisch verhält.

GitLab erneut verbinden oder trennen

Klicken Sie auf Orbit und dann auf New project.
Klicken Sie in Schritt 1 auf Reconnect, um den OAuth-Flow erneut auszuführen, oder auf Disconnect, um die Verbindung zu entfernen.

Reconnect ist der richtige erste Schritt, wenn das Repository-Listing nicht mehr funktioniert: OAuth-Tokens verfallen, und das erneute Verbinden prägt einen neuen aus.

Das Trennen behält Ihre Projekte und deren Deployment-Verlauf, und das Live-Deployment wird weiterhin Traffic bereitgestellt. Was stoppt, ist Push-ausgelöstes Deployment. Deploy Hooks funktionieren auch nicht mehr, da ein Hook den Branch-Head durch die Provider-Verbindung lesen muss, um zu wissen, was gebaut werden soll.