Workflows in Git

Die Workflows eines Arbeitsbereichs können in einem Git-Repository liegen: Der Workflow-Designer pusht sie dorthin und holt sie zurück, und dieselben Dateien kommen als ZIP aus Exportieren (Exportieren, importieren und Git). Diese Seite ist für die, die das Repository pflegen: was darin liegt, wie Sie die Skripte auf Ihrem eigenen Rechner und in der CI prüfen und wie ein Branch in den Arbeitsbereich zurückkommt. Was zurückkommt, ist ein Entwurf; veröffentlicht wird weiterhin mit einem Klick einer Person in der App.

Der Aufbau des Repositorys

Ein Export oder ein Push schreibt:

CLAUDE.md                                 Anweisungen für KI-Agenten (auch AGENTS.md und der Skill darunter)
AGENTS.md
.claude/skills/acriva-workflows/SKILL.md
workflows/
  invoice-approval/                       ein Ordner je Workflow, benannt nach seinem Schlüssel
    workflow.yaml                         die Schritte, der Auslöser, die Einstellungen und die Felder, die er deklariert
    scripts/route.ts                      die Skripte seiner Skript-Schritte
    types/acriva.d.ts                     die Deklarationen des SDK (der Version, die der Workflow festlegt)
    types/tenant.d.ts                     die Typen des Arbeitsbereichs, die dieser Workflow nutzt
    types/route.step.d.ts                 je Skript-Schritt: die Felder, die sein Skript liest und setzt

• workflow.yaml folgt dem veröffentlichten JSON-Schema: Schlüssel in fester Reihenfolge, Schrittnamen als IDs, keine IDs des Arbeitsbereichs, keine Zeitstempel und keine Geheimnisse. Personen, Rollen, Dokumenttypen, Schlagwörter, Akten, Akten-Typen und Kostenstellen stehen mit Schlüssel, E-Mail-Adresse, Name oder Nummer darin, und ein Import ordnet sie den Objekten des importierenden Arbeitsbereichs zu.
• types/ ist für Editoren und die CI geschrieben. Ändern Sie den Ordner nicht: Der Server prüft Skripte gegen seine eigenen Deklarationen, und der nächste Export schreibt den Ordner neu.
• fixtures/<name>.json (optional, Ihre eigenen) enthält synthetische Fälle für acriva workflows test der CLI.
• Ihre eigenen Dateien gehören neben workflows/, in die oberste Ebene: eine README.md, die Konfiguration der CI, das Prüfskript unten.

Was zurückkommt, und woher:

• Beim Holen liest Acriva vom Commit nur workflows/<key>/workflow.yaml und workflows/<key>/scripts/<name>.ts und übergeht alle anderen Dateien. Ein symbolischer Link oder ein Submodul unter workflows/ lässt das Holen scheitern.
• Ein ZIP-Import liest dieselben Dateien und übergeht alle Dateien außerhalb von workflows/, sodass sich ein Repository so, wie es ist, als ZIP-Datei importieren lässt. Unter workflows/ lehnt er jede Datei ab, die ein Paket nicht enthält, und überall in der ZIP-Datei einen symbolischen Link, einen verschlüsselten Eintrag oder einen unsicheren Pfad. In der obersten Ebene lehnt er ab, was das Werkzeug eines KI-Agenten aus einem ausgecheckten Repository ausführen würde: eine .mcp.json, alles in .claude/ außer dem Skill acriva-workflows und eine anders geschriebene CLAUDE.md.
• Ein Paket hat höchstens 54 Workflows und 500 Einträge, seine Ordner eingeschlossen, und eine ZIP-Datei höchstens 10 MB. Die übergangenen Dateien zählen bei beidem mit: Erstellen Sie die ZIP-Datei bei einem größeren Repository nur aus workflows/, zum Beispiel mit git archive --format=zip -o workflows.zip HEAD workflows.

Die Skripte lokal prüfen

Jeder Workflow hat seinen eigenen Ordner types/: Seine tenant.d.ts nennt nur, was dieser Workflow nutzt, und die <skript>.step.d.ts jedes Skript-Schritts typisiert ctx.document.fields mit den Eingaben des Schritts und ctx.setField mit den Feldern, die er setzen darf, wie die Prüfung der App. Prüfen Sie die Typen Skript für Skript mit TypeScript, mit diesen Dateien und dem Import des SDK auf die types/acriva.d.ts des Workflows umgeleitet. Dieses Skript in der obersten Ebene des Repositorys tut das für jedes Skript:

check-scripts.sh

#!/bin/sh
# Type-checks each script against its workflow's types/ and its step's declarations (strict, no emit).
set -eu
config="$(mktemp -d)/tsconfig.json"
status=0
for script in "$PWD"/workflows/*/scripts/*.ts; do
  [ -f "$script" ] || continue
  dir="${script%/scripts/*}"
  step="$dir/types/$(basename "$script" .ts).step.d.ts"
  cat > "$config" <<JSON
{
  "compilerOptions": {
    "strict": true, "noEmit": true, "target": "ES2022", "lib": ["ES2022"],
    "module": "ESNext", "moduleResolution": "Bundler", "types": [],
    "paths": { "@acriva/workflow-sdk": ["$dir/types/acriva.d.ts"] }
  },
  "files": ["$script", "$dir/types/acriva.d.ts", "$dir/types/tenant.d.ts", "$step"]
}
JSON
  echo "checking ${script#"$PWD"/}"
  npx --yes --package typescript@6.0.3 tsc --project "$config" || status=1
done
exit $status

Führen Sie es mit sh check-scripts.sh aus (Node.js 20 oder neuer). Ein Editor wie VS Code zeigt dieselben Fehler mit denselben Einstellungen in einer eigenen tsconfig.json des Skripts; halten Sie diese Datei aus einer ZIP-Datei heraus, die Sie importieren.

Die Prüfung des Servers geht weiter als TypeScript: Sie prüft die Skripte auch mit den Regeln von Acriva (kein fetch, keine Timer, nur deklarierte Wirkungen), mit ACR-S-Codes. Mit einem API-Schlüssel führt die CLI @acriva/cli diese Prüfung auf der Kommandozeile aus: acriva workflows validate.

Eine CI-Prüfung mit tsc und dem JSON-Schema

Dieselben beiden Prüfungen in der CI finden ein fehlerhaftes Skript oder eine workflow.yaml, die das Format nicht erlaubt, bevor jemand den Branch holt. Für GitHub Actions:

.github/workflows/workflows.yml

name: workflows
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Type-check the scripts
        run: sh check-scripts.sh
      - name: Check workflow.yaml against the JSON Schema
        run: pipx run --spec check-jsonschema==0.33.0 check-jsonschema --schemafile https://docs.acriva.de/schemas/workflow.schema.json workflows/*/workflow.yaml

In einem anderen CI-Dienst führen Sie dieselben beiden Befehle in einem Job mit einem Image aus, das Node.js und Python hat. Das Schema prüft die Form der Datei; Verweise auf den Arbeitsbereich (gibt es die Rolle, gibt es das Schlagwort) werden beim Import des Workflows geprüft, und das Veröffentlichen prüft den ganzen Workflow noch einmal.

Einen Branch als Entwurf importieren

Im Workflow-Designer holt die Ansicht Git einen Branch, einen Tag oder einen Commit:

1. Öffnen Sie einen Workflow im Designer und wählen Sie in der Werkzeugleiste den Chip Git: mit dem Branch (oder Git in der Seitenleiste des Vollbild-Skripteditors).
2. Wählen Sie unter Holen die Art der Referenz (Branch, Tag oder Commit), geben Sie ihren Namen oder SHA ein und wählen Sie Holen als Entwurf.
3. Gibt es einen Verweis der geholten Workflows im Arbeitsbereich nicht, öffnet Import fortsetzen den Import: Ordnen Sie unter Verweise zuordnen jeden einem Objekt des Arbeitsbereichs zu, oder entfernen Sie ihn.
4. Vergleichen zeigt die workflow.yaml und die Skripte jedes Workflows, links Ihr aktueller Entwurf, rechts die geholten Dateien. Als Entwurf übernehmen ersetzt die Entwürfe.
5. Prüfen Sie den Entwurf im Designer und wählen Sie Veröffentlichen. Vorher wird nichts veröffentlicht.

Einen Commit über seinen SHA zu holen, braucht eine Gegenstelle, die es erlaubt; sonst holen Sie einen Branch oder einen Tag. Ein Arbeitsbereich kann 10 Übertragungen in 10 Minuten beginnen, eine nach der anderen. Dasselbe Holen ist POST /api/v1/t/{tenant}/workflows/git-remote/pull mit {"ref": "feature/skonto", "kind": "Branch"} (API-Referenz), und acriva workflows push importiert einen lokalen Checkout ohne Gegenstelle als Entwürfe.