Branch-Umgebungen

Eine Branch-Umgebung ist eine Kopie eines Projekts auf einem anderen Branch seines Repositorys. Du pushst feature/login, und neben https://shop.test gibt es https://shop-feature-login.test, auf dem dieser Branch läuft, mit eigenen Containern und einer eigenen Kopie der Daten. Genau das willst du, wenn eine Kollegin fragt: “Kann ich mal durchklicken, bevor wir mergen?”

Alles dazu findest du im Bereich Branches des Projekts. Das Projekt braucht unter Git ein Repository und einen geklonten Checkout, denn die Umgebung startet vom Arbeitsverzeichnis des Eltern-Projekts aus.

Eine anlegen

Klick auf Branches des Repositorys laden, wähl einen Branch und dann Umgebung anlegen. Envoryx kopiert das Projekt dann genauso wie Duplizieren, mit allen Haken gesetzt:

• die Projektdateien, auch die, die git ignoriert (.env, vendor/, node_modules/), damit die Kopie läuft, ohne alles neu zu installieren,
• jede Datenbank, als Dump in den eigenen Datenbankserver der Umgebung importiert,
• die Objekte im Bucket,
• die Worker und Cron-Jobs, die Umgebungsvariablen und die Repository-Anbindung.

Nach dem Kopieren wechselt das Arbeitsverzeichnis auf den Branch (git checkout -f und git clean -fd, das entfernt nicht versionierte Dateien, die der Branch nicht ignoriert), die Umgebung startet und ihre Deploy-Befehle laufen einmal. Das Kopieren dauert so lange, wie das Projekt groß ist; ein Projekt mit ein paar Gigabyte Uploads ist also nicht in Sekunden fertig.

Die Umgebung ist ein eigenes Projekt und heißt nach beiden, etwa Shop (feature/login) mit dem Slug shop-feature-login. Zusätzliche Domains und Backup-Zeitpläne bleiben wie bei jeder Kopie beim Eltern-Projekt. Und was du in einer Kopie selbst nachziehst, gilt hier genauso: Hält die Anwendung ihre eigene URL in der Datenbank, schickt dich die Umgebung zum Eltern-Projekt zurück, bis du sie änderst.

Umgebungen anlegen darf, wie jedes Projekt anlegen, nur ein Admin der ganzen Instanz. Eine Umgebung kann keine eigenen Umgebungen haben; du legst sie immer am Eltern-Projekt an.

Deploy-Befehle

Was nach dem Kopieren oder einem Pull passiert, bestimmst du. Unter Branch-Einstellungen → Deploy-Befehle trägst du einen Befehl pro Zeile ein, zum Beispiel:

composer install
php artisan migrate --force
php artisan optimize:clear

Sie laufen nacheinander im Anwendungscontainer, und zwar als Projektbesitzer, damit die Dateien, die dabei entstehen, dem richtigen Benutzer gehören. Anwendungscontainer ist der erste von PHP, Python, Go, Ruby, Java, .NET und Node.js, den das Projekt hat. Neben PHP ist das der PHP-Container, und der hat kein npm. Lass Asset-Builds also aus der Liste und führ npm ci oder npm run build im Bereich Aktionen der Umgebung aus, der dafür den Node.js-Container nimmt. Der erste Befehl, der fehlschlägt, bricht das Deploy ab, und die Umgebung zeigt Deploy fehlgeschlagen mit der Ausgabe. Bis zu 20 Befehle passen hinein, jeder eine einzelne Zeile. Für ein Deploy muss die Umgebung laufen.

Im Bereich Branches der Umgebung selbst gibt es zwei Knöpfe: Pullen und deployen holt zuerst ihren Branch (nur Fast-Forward, Commits, die du in der Umgebung gemacht hast, bleiben also erhalten, und ein auseinandergelaufener Branch schlägt fehl, statt überschrieben zu werden), Deploy-Befehle ausführen lässt den Pull weg. Dort siehst du auch den Commit, die Zeit des letzten Deploys und seine Ausgabe.

Das Repository beobachten

Mit Repository beobachten fragt Envoryx alle paar Minuten beim Repository nach, welche Branches es gibt. Das ist ein schlichtes git ls-remote mit den Zugangsdaten des Projekts, du brauchst also keinen Webhook, und es klappt mit jedem Git-Server, von dem Envoryx klonen kann. Abfragen alle (Minuten) legt den Abstand fest; leer heißt 5.

Bei jeder Abfrage kann dreierlei passieren:

1. Ein Push auf den Branch einer Umgebung wird gepullt und deployt, solange die Umgebung läuft. Ein gescheitertes Deploy, ob beim Pull oder bei einem der Befehle, wird für denselben Commit nicht wiederholt (und du bekommst eine Benachrichtigung, nicht eine pro Prüfung); der nächste Push versucht es neu.
2. Ein gelöschter Branch nimmt seine Umgebung mit, samt Dateien, Datenbank und Volumes. Dafür ist es gedacht, aber du solltest es wissen, bevor du einen Branch löschst, den du dir noch ansehen willst.
3. Ein neuer Branch, der zu einem Muster passt, unter Branches mit automatischer Umgebung bekommt eine Umgebung. Muster sind Globs, eins pro Zeile, etwa feature/* oder fix/*; * passt nicht auf /. Bleibt das Feld leer, entsteht keine Umgebung von selbst, das Beobachten hält dann nur deine von Hand angelegten aktuell.

Envoryx legt pro Abfrage höchstens eine neue Umgebung an und hört bei Höchstens automatische Umgebungen auf (5, wenn leer, höchstens 50). Die Grenze zählt jede Umgebung des Projekts, auch die von Hand angelegten. Scheitert das Anlegen, bekommst du eine Benachrichtigung, und Envoryx versucht es mit dem nächsten Commit des Branches wieder, nicht bei jeder Abfrage, denn jeder Versuch kopiert das ganze Projekt.

Ohne Beobachten wird nichts von selbst gelöscht. Eine Umgebung, die du nicht mehr brauchst, löschst du wie jedes Projekt über ihr Menü Weitere Aktionen. Das Eltern-Projekt selbst lässt sich nicht löschen, solange es noch Umgebungen hat; Envoryx nennt sie dir und bittet dich, sie zuerst zu löschen.

Ungenutzte Umgebungen stoppen

Fünf Feature-Branches mit je einer Datenbank läppern sich. Ungenutzte Umgebungen stoppen nach (Tagen) stoppt eine Umgebung, die so lange niemand geöffnet hat, gezählt ab der letzten Anfrage über den Proxy oder dem letzten Start. Das geht mit und ohne Beobachten. Eine gestoppte Umgebung behält ihre Dateien und Daten; starte sie einfach wieder, wenn du sie brauchst. Leer heißt nie.

Rollen

Eine Umgebung hat keine eigenen Rollen. Wer am Eltern-Projekt eine Projektrolle hat, hat dieselbe an der Umgebung, bei jeder Prüfung nachgeschaut und nicht einmal kopiert. Eine Rolle, die du später am Eltern-Projekt änderst, gilt also sofort für jede Umgebung. In der Projektliste unter Einstellungen → Benutzer → Projekte tauchen Umgebungen nicht auf, siehe Benutzer und Rollen.

Benachrichtigungen, CLI und MCP

Zwei Ereignisse für Benachrichtigungen gehören zu Branch-Umgebungen: Branch-Umgebung fehlgeschlagen (standardmäßig an) für ein gescheitertes Anlegen oder Deploy, und Branch-Umgebung geändert für eine, die angelegt, mit ihrem Branch gelöscht oder wegen Inaktivität gestoppt wurde.

Aus einem Skript oder einer Pipeline:

envoryx project branches shop                      # Umgebungen, Commit, Deploy-Status, URL
envoryx project branch shop feature/login          # eine anlegen
envoryx project deploy shop-feature-login          # pullen und deployen (--no-pull: nur deployen)

Ein KI-Assistent bekommt dasselbe über die MCP-Werkzeuge list_branch_environments, create_branch_environment und deploy_branch_environment.