Preview-Umgebungen

Eine Preview ist eine lauffähige, per-Ticket bootbare Umgebung: Spedy klont das Repository deines Projekts, spielt einen Datenbank-Snapshot ein und startet die Anwendung (z. B. Shopware oder Magento). Du siehst den laufenden Shop als Iframe neben dem Ticket — und genau dort nimmt der KI-Coding-Agent seine Änderungen vor.

Wie es funktioniert

Wenn du ein Ticket öffnest und die Preview startest, bootet Spedy einen Container-Stack, der:

1. das Preview-Repo des Projekts klont,
2. einen Datenbank-Snapshot einspielt und
3. die Anwendung startet.

Pro Ticket gibt es genau eine Preview. Die Preview-URL ist org-eindeutig und nur mit gültiger Spedy-Session erreichbar — siehe Sicherheit & Isolation.

Eigener Stack? Wenn dein Repo ein eigenes docker-compose.yml mitbringt, statt ein Shopware-/Magento-Template zu nutzen, beschreibt Preview-Konfiguration (BYOC) die .spedy/preview.yml, die Spedy sagt, welcher Service und Port geroutet wird.

Voraussetzungen

Preview Environments sind ein Beta-Feature, das in zwei Schritten aktiviert werden muss:

1. Organisation: Ein Admin aktiviert „Live Preview" unter Einstellungen → Features (dort mit einem „Beta"-Badge gekennzeichnet).
2. Board: Jedes Board muss anschließend unter Board-Einstellungen → Features einzeln opt-in.

Ohne beide Schalter ist der Preview-Button im Ticket-Header nicht sichtbar und die Preview-Seite zeigt einen Hinweis mit Anleitung zur Aktivierung.

Zusätzlich braucht deine Organisation eine aktive GitHub-Integration unter Einstellungen → Integrationen. Ohne sie zeigt der Repository-Bereich einen Hinweis statt der Repo-Auswahl.

Projekt einrichten

Öffne Projekt → Einstellungen → Preview.

Repository verbinden

Im Abschnitt Repository:

1. Klick auf Repo verbinden und wähl aus dem Dropdown ein GitHub-Repo (die Liste kommt aus der GitHub-Integration deiner Organisation).
2. Bestätige den Base-Branch (wird aus dem Repo vorausgefüllt).
3. Klick auf Verbinden.

Das frisch verbundene Repo wird automatisch als Preview-Repo markiert (grünes Badge). Ein Board kann mehrere Repositories haben (z. B. für den Runner oder CI) — aber genau eines ist das Preview-Repo. Über Für Preview verwenden lässt sich die Markierung auf ein anderes Repo umhängen.

Der Preview-Container klont dieses Repo bei jedem Boot. Branches und Commits des KI-Agents werden dorthin gepusht.

Datenbank-Snapshot hochladen

Ohne Snapshot bootet eine frische Preview mit der leeren Demo-Datenbank. Für realistische Daten nutzt du den Abschnitt Datenbank-Snapshots:

1. Vergib einen Namen (z. B. prod-baseline).
2. Wähl einen .sql- oder .sql.gz-Dump (bis 4 GB).
3. Klick auf Hochladen.
4. Beim Eintrag auf Als Default setzen → er bekommt ein grünes Projekt-Default-Badge.

Der Projekt-Default wird in jede Preview des Projekts eingespielt. Pro Ticket lässt er sich überschreiben — siehe Datenbank pro Ticket überschreiben.

Preview im Ticket nutzen

Klick auf das Preview-Icon im Ticket-Header (oder öffne direkt …/tickets/<id>/preview). Beim ersten Mal steht da „Preview ist aus" — klick auf Preview starten. Der erste Boot dauert ~30–60 s (Container-Start + Repo-Clone + Snapshot-Restore), danach nur Sekunden.

Ist die Preview oben, zeigt die linke Hälfte den Shop als Iframe, die rechte das Ticket-Panel bzw. den Agent:

Branch oder PR auswählen

Standardmäßig klont die Preview den Standard-Branch des Preview-Repos. Auf der Start-Karte (solange die Preview gestoppt ist) findest du ein durchsuchbares Branch-Dropdown, mit dem du stattdessen einen anderen Stand booten kannst:

• Standard-Branch — die Voreinstellung; ohne Auswahl ändert sich nichts am bisherigen Verhalten.
• Branches und Pull Requests des Tickets — alle Branches und PRs, die mit dem Ticket verknüpft sind (z. B. der Branch, auf dem der KI-Agent gearbeitet hat).

Wähle den Branch hinter einem offenen PR und klick auf Preview starten — die Preview bootet exakt den Code, der zur Review ansteht. Die Auswahl gilt für diesen Boot; ein späterer Reset baut die Preview auf demselben Branch wieder auf.

Idle-Timeout

Solange der Preview-Tab offen ist, hält ein Heartbeat den Container am Leben. Nach ~15 Minuten ohne Aktivität wird er automatisch gestoppt — beim nächsten Mal einfach neu starten.

Datenbank pro Ticket überschreiben

Soll ein bestimmtes Ticket gegen einen anderen Dump booten (z. B. um einen kundenspezifischen Bug zu reproduzieren), öffne das Ticket → Tab Eigenschaften → Feld Preview-DB.

Auflösungsreihenfolge beim Boot (höchste Priorität zuerst):

1. Per-Ticket-Override (dieses Feld)
2. Projekt-Default (siehe oben)
3. Template-Seed (die Demo-Datenbank des Images selbst — z. B. die von dockware bei Shopware)

Die Auswahl greift beim nächsten Container-Boot — eine laufende Preview behält ihre Datenbank bis zum Neustart.

Preview-Agent steuern

Der KI-Coding-Agent arbeitet direkt in der Preview. Was er dabei darf, legst du pro Projekt fest: Öffne Projekt → Einstellungen → Agent-Einrichtung und scrolle zum Abschnitt Preview-Agent. Bearbeiten kann die Einstellungen, wer Runner verwalten darf — alle anderen sehen sie schreibgeschützt.

Berechtigungen

Die Karte Berechtigungen enthält drei Bereiche:

• Pull Request automatisch erstellen (Standard: an) — Nach jedem erfolgreichen Run committet und pusht Spedy die Änderungen des Agents und öffnet automatisch einen Pull Request. Existiert für den Branch bereits ein PR, wird er weiterverwendet und im Ticket verlinkt. Schaltest du den Toggle aus, erstellst du PRs wie früher manuell über den PR erstellen-Button im Ticket.

• Zugriff auf Preview & Container — Drei Schalter steuern, wie der Agent seine eigenen Änderungen prüfen darf:

  • Live-Preview per HTTP abrufen (preview_fetch) — der Agent kann die laufende Preview aufrufen und die Antwort prüfen.
  • Befehle in den Preview-Containern ausführen (preview_exec) — z. B. einen Testlauf oder ein Build-Kommando.
  • Container-Logs lesen (preview_logs) — um Fehlern auf den Grund zu gehen.

  Alle drei sind standardmäßig an. Der Zugriff läuft über ein abgesichertes Gateway pro Run: kein Shell-Zugriff, keine Git-Zugangsdaten, jeder Aufruf wird protokolliert.

• Werkzeuge einschränken — Standardmäßig darf der Agent Dateien lesen und bearbeiten. Aktiviere den Toggle, um das erlaubte Werkzeug-Set explizit festzulegen; danach wählst du die Werkzeuge (Lesen, Bearbeiten, Suchen, Web-Recherche u. a.) einzeln per Checkbox. Eine Shell (Bash) steht nie zur Auswahl — Befehle in der Preview definierst du stattdessen als Pre-/Post-Run-Befehle (siehe unten).

Pre- und Post-Run-Befehle

Unter den Berechtigungen findest du zwei Karten für Befehle, die der Runner rund um jeden Agent-Run in den Preview-Containern ausführt:

• Pre-Run-Befehle laufen vor dem Agenten — z. B. npm ci, um Abhängigkeiten zu installieren, oder ein Seed-Skript. Schlägt ein Pre-Run-Befehl fehl, bricht der Run ab, bevor der Agent startet.
• Post-Run-Befehle laufen nach dem Agenten — z. B. bin/console theme:compile && bin/console cache:clear, damit die Änderung in der Preview sichtbar wird. Ein Fehler erzeugt hier nur eine Warnung; der Run gilt weiterhin als erfolgreich.

So legst du einen Befehl an:

1. Trage optional links einen Compose-Service ein (leer = der Primär-Container deiner Preview).
2. Gib den Befehl ein, z. B. npm ci.
3. Klick auf Hinzufügen.

Jeder Befehl lässt sich über seinen Schalter deaktivieren, ohne ihn zu löschen, und über das X entfernen. Pro Befehl gilt ein Standard-Timeout von 5 Minuten; pro Phase sind bis zu 20 aktive Befehle möglich.

Hinweis: Ist für das Projekt ein Runner-Team hinterlegt, gilt der System-Prompt der ersten aktiven Stage (inklusive zugewiesener Skills) auch für Preview-Runs — der Agent verhält sich in der Preview genauso wie bei Runner-Jobs.

Sicherheit & Isolation

• Org-Isolation. Jede Preview bekommt einen org-eindeutigen Slug, sodass zwei Organisationen nie kollidieren — auch nicht bei gleichem Board-Prefix. Jeder Aufruf einer Preview wird gegen die Organisation des Aufrufers geprüft.
• Session-Gate. Die Preview-URL ist nur mit gültiger Spedy-Session und nur für die eigene Organisation erreichbar.
• Private Repos. Das Klonen privater Repositories nutzt die verbundenen GitHub-Credentials deiner Organisation.

Adressleiste und Navigation

Die Preview-Ansicht verhält sich wie ein Browser: Die Adressleiste zeigt die aktuelle URL und erlaubt Navigation per Enter oder den Refresh-Button. Beim Navigieren innerhalb einer laufenden Preview erscheint ein dünner Fortschrittsbalken und ein Spinner in der Adressleiste — statt des vollen Boot-Overlays.

Das Boot-Overlay erscheint nur bei echten Container-Zuständen (Kaltstart, Stoppen, Fehler).

Stoppen und Status

Stoppen während des Starts

Du kannst eine Preview jederzeit stoppen — auch während sie noch hochfährt. Der Stop-Button ist sowohl im Boot-Overlay als auch in der Toolbar verfügbar.

Status-Indikator am Ticket

Der Ticket-Header zeigt einen farbigen Punkt neben dem Preview-Link:

• Grün — Preview läuft
• Gelb — Preview wird gestartet
• Rot — Preview ist degradiert

Laufende Previews

Zwei Oberflächen zeigen alle laufenden Previews deiner Organisation:

• Dashboard-Karte — auf dem Work-Dashboard mit der Möglichkeit, direkt zur Preview zu springen oder sie zu stoppen
• Board-Header-Chip — zeigt die Anzahl laufender Previews auf dem Board, Klick öffnet ein Popover mit Details

Beide verschwinden automatisch, wenn keine Previews laufen.

Reset

Der Reset-Button in der Preview-Toolbar löscht den geklonten Code und baut die Preview komplett neu auf — vom Branch, mit dem sie gestartet wurde (dem Standard-Branch, falls du keinen ausgewählt hast). Das ist nützlich, wenn die Preview auf einem veralteten Stand festsitzt oder ein fehlerhafter Build den Container unbrauchbar gemacht hat.

Nach dem Reset bootet die Preview automatisch neu.

Fehlerbehebung