Ein Windmill-Repository importieren

SupaCloud kann ein Windmill-wmill sync-Repository — dessen Flows, rohe Apps und Skripte — als native Workflows in einen Workspace importieren. Wenn das Repository unter db/migrations/ Datenbankmigrationen mitbringt, wendet SupaCloud dieses Schema beim Import auf eine von dir gewählte PostgreSQL-Ressource an, sodass die importierten Flows ihre Tabellen schon beim ersten Lauf haben.

Das ist eine Admin-Aufgabe: der Import-Endpunkt erfordert einen Workspace-Admin.

Hinweis

Ein Windmill-Repository bringt alles mit außer einer einzigen deployment-spezifischen Tatsache: welche Datenbank das gemeinsame Schema beherbergt. Diese PostgreSQL-Ressource bindest du einmalig im Import-Assistenten — alles andere (der Schemaname und seine Mandantenisolierung) wird aus dem Repository gelesen.

Bevor du startest

• Du bist Workspace-Admin.
• Das Repository ist erreichbar: eine Git-URL und, für ein privates Repository, eine unter Ressourcen konfigurierte Git-Anmeldedatei.
• Enthält das Repository einen db/migrations/-Ordner, lege unter Ressourcen eine PostgreSQL-Ressource für das gemeinsame Schema an (oder wähle eine vorhandene). Bevorzuge in der Produktion eine least-privileged Rolle mit Rechten nur auf dieses Schema statt eines Superusers.

Den Import durchführen

1. Den Import-Assistenten öffnen. Gehe zu Workflows und wähle Import → Windmill-Repository.

2. Auf das Repository zeigen. Gib die Git-URL ein und wähle für ein privates Repository die Git-Anmeldedatei. SupaCloud klont das Repository und scannt es zu einem Importplan — die gefundenen Flows, Apps und Skripte sowie ein eventuelles db/migrations/, das angewendet wird.

3. Die Datenbankressource binden. Enthält der Plan ein Datenbankschema, wähle die PostgreSQL-Ressource, auf die es angewendet wird. Diese Bindung ist die einzige deployment-spezifische Entscheidung; Schemaname und Isolierung liest SupaCloud aus dem Repository.

4. Prüfen und anwenden. Bestätige den Plan. SupaCloud erstellt die Workflows (jeder behält seinen Windmill-Ordner im Namen, f/blockworx/bank_sync wird also zu blockworx/bank_sync), erfasst Zeitpläne und HTTP-Trigger und wendet das Datenbankschema auf die gebundene Ressource an.

Zero-Touch-Datenbankschemas

Ein Repository, dessen db/migrations/-Ordner keine SupaCloud- db/namespace.yaml mitbringt, wird trotzdem ohne manuelle Einrichtung importiert: SupaCloud leitet den Schemanamen aus dem CREATE SCHEMA- Statement und die Mandantenisolierung aus dem SQL ab. Ein Schema, dessen Tabellen eine entity-Spalte deklarieren, wird pro Entität isoliert; sonst ist es gemeinsam genutzt ohne mandantenspezifische Überlagerung.

Das Schema wird per Name find-or-create angewendet, append-only und prüfsummengesichert — ein erneuter Import wendet eine bereits gelaufene Migration nie erneut an. Um die abgeleitete Form zu überschreiben, füge dem Repository eine db/namespace.yaml hinzu; sie hat Vorrang.

Tipp

Nur ein einfacher, kleingeschriebener Schemaname (passend zu [a-z_][a-z0-9_]* und kein reservierter Name wie public oder ein pg_-Schema) wird angewendet. Ist das Zielschema eines Repositories kein einfacher Bezeichner, deklariere es explizit in db/namespace.yaml.

Ressourcen- und Variablen-Referenzen

Ein Windmill-Flow-Modul liest häufig eine Zugangsdaten oder eine Einstellung über eine resource("f/…")- oder eine variable("u/…")-Referenz. SupaCloud importiert diese als echte Bindungen am erzeugten Code-Node — nicht als tote Platzhalter.

• resource("f/…") wird zu einer Ressourcen-Bindung. Ein Code-Node, der eine Ressource bindet, läuft in der berechtigungsgeführten Sandbox (Python/TypeScript) mit standardmäßig verweigertem Egress: das Skript erreicht nur den Host der gebundenen Ressource und liest die aufgelöste Zugangsdaten über einen host-vermittelten Accessor — es hält nie das rohe Secret. Eine postgresql-Ressource gewährt zusätzlich einen host-vermittelten, abgesicherten Datenbankaufruf (standardmäßig nur lesend; siehe unten). Der Konverter ordnet jede Referenz einer Workspace-Ressource per Name zu und gibt eine Warnung für jede Bindung aus, die du prüfen oder neu binden solltest — öffne den Node im Builder und bestätige, dass die referenzierte Ressource in diesem Workspace existiert.

  Der Name ist ordner-qualifiziert: Windmill-Ordner und Ressourcenname werden mit einem Unterstrich verbunden, aus f/blockworx/imap_info wird also blockworx_imap_info und aus f/c2ost/imap_info wird c2ost_imap_info. Zwei Ordner, die denselben Ressourcennamen verwenden, bleiben damit zwei getrennte Ressourcen — sie fallen nie auf eine gemeinsame Zugangsdaten-Ressource zusammen. Das Präfix f/ bzw. u/ entfällt; jedes weitere Pfadsegment bleibt erhalten, wird kleingeschrieben, und alles außer Buchstaben und Ziffern wird zu einem Unterstrich. Aus f/shared/anthropic wird shared_anthropic — der Shared-Ordner wird wie jeder andere qualifiziert.

• variable("u/…") wird zu einer Workspace-Umgebungsvariablen-Injektion. Die passende Workspace-Umgebungsvariable (per Schlüssel — dem letzten Pfadsegment) wird zur Laufzeit host-seitig aufgelöst und in den Node injiziert, least-authority: nur die Variablen, die das Skript tatsächlich liest, werden injiziert. Eine als Secret markierte Variable wird host-seitig entschlüsselt und nie in der Workflow-Definition gespeichert. Stelle sicher, dass eine Umgebungsvariable dieses Schlüssels unter Ressourcen → Umgebungsvariablen existiert.

Achtung

Datenbank-Schreibzugriffe aus einem gebundenen Code-Node sind standardmäßig deaktiviert — eine gebundene postgresql-Ressource bedient nur lesende Abfragen, sofern du Schreibzugriffe an dieser Bindung nicht ausdrücklich aktivierst. Aktiviere Schreibzugriffe nur für einen Node, dem du das Mutieren dieser Datenbank zutraust.

Ein Code-Node, der keine Ressource bindet, bleibt hermetisch (kein Netzwerk, keine Datenbank) — unverändert gegenüber einem schlichten importierten Snippet. Bindungen sind eine First-Party-, workspace-eigene Fähigkeit; im Marketplace veröffentlichte Workflows tragen sie nie.

Der Einstiegspunkt eines Schritts

Windmill ruft die main(...)-Funktion eines Schritts für dich auf. SupaCloud führt die Datei des Schritts aus, deshalb ergänzt der Import den Aufruf selbst — du schreibst den Einstiegspunkt nicht von Hand um:

• die Argumente stammen aus den input_transforms des Flows und werden über den Parameternamen zugeordnet (nie über die Position, damit eine geänderte Reihenfolge der Eingaben zwei Argumente nicht vertauschen kann);
• ein async-Einstiegspunkt wird abgewartet (TypeScript) bzw. zu Ende geführt (Python), sodass der Schritt einen Wert liefert statt eines offenen Promise;
• der Rückgabewert wird zum Schritt-Ergebnis, das der nächste Schritt liest. Ein Schritt ohne Rückgabewert liefert kein Ergebnis — das ist ein gültiges Resultat, kein Fehler;
• ein Einstiegspunkt, der eine Ausnahme wirft, lässt den Schritt jetzt fehlschlagen, mit Fehler und Stack im Log, statt erfolgreich und ohne Ergebnis zu enden;
• ein Ergebnis über der Größengrenze für Schritt-Ergebnisse schlägt mit einer Meldung fehl, die Grenze und tatsächliche Größe nennt. Es wird nichts still abgeschnitten.

Hinweis

Zwei Formen werden gemeldet statt umgeschrieben. Ein Einstiegspunkt, dessen Parameter sich nicht auf benannte Eingaben abbilden lassen (ein destrukturierter Parameter, ein Rest-Parameter, ein Python-Marker für rein positionale Parameter), erhält keinen generierten Aufruf — der Import weist darauf hin, dass der Schritt kein Ergebnis liefert, bis du ihn selbst verdrahtest. Ein Schritt, der seinen Einstiegspunkt bereits selbst aufruft oder sein Schritt-Ergebnis selbst schreibt, bleibt unangetastet, damit seine Seiteneffekte nie doppelt laufen.

Siehe auch

• Migrationen ausführen und aktualisieren
• Secrets in der UI verwalten
• ADR 0057 — Datenbank-Namespaces und Shared-Schema-Migrationen
• ADR 0058 — Ressourcen- und Zugangsdatenmodell für importierte Windmill-Flows