Event-Pipelines

Stand: 29.10.2026. Eine Pipeline gehört zu genau einem Event. Tracklytic überwacht Zustände und Abhängigkeiten; externe Prozesse führen die eigentliche Arbeit aus und melden ihren Zustand. Nur manuell ausgelöste Step-Actions führen die konfigurierten Webhooks aus. Ein freigegebener Step startet nicht automatisch einen Webhook.

Event mit Pipeline erstellen

POST /v1/event, Authorization: Bearer <API_TOKEN>. Projekt und Kanal wie bisher als Slugs.

{
  "project": "my-project",
  "channel": "deployments",
  "event": "Release 2.4",
  "notify": false,
  "pipeline": {
    "timeout": 1800,
    "timeoutAlert": {
      "logLevel": "critical",
      "notify": true
    }
  },
  "steps": [
    {
      "id": "build",
      "name": "Build",
      "stage": "Build"
    },
    {
      "id": "tests",
      "name": "Tests",
      "stage": "Build",
      "allowFailure": true
    },
    {
      "id": "review",
      "name": "Freigabe",
      "stage": "Review",
      "requires": [
        "build",
        "tests"
      ],
      "actions": [
        {
          "type": "form",
          "maxRuns": 1,
          "allowRetryOnFailure": true,
          "confirmation": "Dieses Release freigeben?",
          "properties": {
            "buttonText": "Freigabe senden",
            "fields": [
              {
                "name": "comment",
                "type": "text",
                "label": "Kommentar",
                "required": true
              }
            ]
          },
          "action": [
            {
              "type": "webhook",
              "properties": {
                "url": "https://example.org/releases/approve",
                "method": "POST",
                "body": {
                  "comment": "{{inputs.comment}}"
                },
                "expects": {
                  "code": 200
                }
              }
            }
          ]
        }
      ]
    },
    {
      "id": "deploy",
      "name": "Deployment",
      "stage": "Deploy",
      "requires": [
        "review"
      ]
    },
    {
      "id": "report",
      "name": "Bericht",
      "stage": "Nachbereitung",
      "requires": [
        "deploy"
      ],
      "required": false,
      "allowFailure": true
    }
  ]
}

Antwort für Pipeline-Events (HTTP 201, gekürztes Beispiel):

{
  "id": "EVENT_ID",
  "status": "waiting",
  "pipeline": {
    "revision": 0
  }
}

Die ID wird für Step-Updates benötigt. Events ohne Pipeline behalten ihre bisherige leere Erstellungsantwort und ihre bisherigen Statusregeln.

steps enthält 1–200 Steps, maximal 20 Action-Komponenten pro Step. pipeline ist optional; ohne timeout läuft keine Frist. pipeline ohne Steps ist ungültig. Step-IDs sind innerhalb eines Events eindeutig, maximal 80 Zeichen, Zeichen A-Z a-z 0-9 _ . -, beginnend mit Buchstabe oder Ziffer. Name maximal 200, Stage maximal 80, Beschreibung maximal 5000 Zeichen. IDs sind stabil und werden beim Update nicht umbenannt.

Stages, Parallelität und Abhängigkeiten

Stages sind benannte Gruppen in der Anzeige. Ihre Reihenfolge entspricht ihrem ersten Vorkommen im Step-Array; innerhalb einer Stage bleibt die Array-Reihenfolge erhalten. Die Verbindungslinien zeigen die expliziten requires-Abhängigkeiten zwischen Steps. Ein Klick öffnet die Details und Actions als animiert ausklappende Karte unter dem Graphen. Die Stage-Gruppen erzeugen keine zusätzlichen Ausführungsbarrieren.

Nur requires bestimmt die Freigabe. Ohne Vorgänger kann ein Step sofort starten; mehrere solcher Steps sind parallel möglich. Abhängigkeiten dürfen innerhalb derselben Stage oder über mehrere Stages verlaufen. Alle Referenzen müssen im vollständigen Graphen existieren. Doppelte IDs, Zyklen und Selbstabhängigkeiten werden vor dem Schreiben abgelehnt.

Ein Vorgänger ist erfüllt bei success, bei failed mit allowFailure: true oder bei skipped mit required: false. Ein noch wartender optionaler Vorgänger wird nicht automatisch übersprungen. Wer ihn als Voraussetzung verwendet, muss ihn erfolgreich abschließen oder explizit überspringen.

required und allowFailure

Diese Eigenschaften sind unabhängig. Standard: required: true, allowFailure: false.

Optionale wartende Steps halten den Gesamterfolg nicht auf. Laufende optionale Steps tun dies, damit ein späterer harter Fehler nicht hinter einem Erfolg verborgen wird. Eine ausschließlich aus optionalen wartenden Steps bestehende Pipeline ist bereits success. Ein erforderlicher Step kann nicht übersprungen werden.

Step melden und Folgeschritte ergänzen

Extern: POST /v1/event/{eventId}/step, API-Token des zugehörigen Projekts. Im angemeldeten Frontend: PATCH auf denselben Pfad mit Access-JWT und bestehender Projektmitgliedschaft. Endpunkte prüfen Event-Projektzugehörigkeit unabhängig vom verwendeten Ersteller-Token. Gelöschte Events können nicht aktualisiert werden.

curl -X POST 'https://api.tracklytic.de/v1/event/EVENT_ID/step' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "build",
  "status": "running",
  "message": "Build gestartet"
}'

{
  "id": "build",
  "status": "success",
  "message": "Artefakt hochgeladen"
}

Der Body benötigt id eines bestehenden Steps und mindestens status oder steps. Mit steps werden neue Definitionen angehängt, keine vorhandenen ersetzt:

{
  "id": "deploy",
  "status": "success",
  "steps": [
    {
      "id": "smoke",
      "name": "Smoke-Test",
      "stage": "Verify",
      "requires": [
        "deploy"
      ]
    },
    {
      "id": "archive",
      "name": "Archivieren",
      "stage": "Verify",
      "requires": [
        "smoke"
      ]
    }
  ]
}

Statusänderung und Erweiterung sind atomar. Neue IDs müssen eindeutig sein; Abhängigkeiten dürfen bestehende und im selben Request neue Steps referenzieren. Die Grenze von 200 gilt für den gesamten resultierenden Graphen. Ein neuer Pflicht-Step kann eine erfolgreiche Pipeline wieder auf waiting setzen. Die ursprüngliche Timeout-Frist wird dabei nicht verlängert; nach Fristende sind Erweiterungen, die die Pipeline wieder öffnen würden, gesperrt.

Zustandsregeln

Step-Status: waiting, running, success, failed, skipped, cancelled.

• Initial ist waiting; ein initialer anderer Zustand ist erlaubt, wenn alle Vorgänger im mitgelieferten Graphen erfüllt sind.
• waiting kann bei erfüllten Vorgängern direkt in running oder einen Endzustand wechseln. So kann ein externer Dienst nur das Endergebnis melden.
• running kann in einen Endzustand wechseln. Rücksetzen auf waiting ist nicht erlaubt.
• failed kann explizit nach running wechseln, solange noch kein direkter Nachfolger gestartet wurde. Damit bleiben bereits ausgeführte Nachfolger konsistent.
• success, skipped und cancelled eines Steps sind unveränderlich. Eine identische Statusmeldung darf wiederholt werden; sie erzeugt einen weiteren Audit-Eintrag, aber keine externe Ausführung.
• Ein Step mit laufender Action kann nicht parallel extern geändert werden.
• Eine Pipeline mit Eventstatus cancelled oder timed_out ist geschlossen. Verspätete Action-Antworten werden protokolliert, ändern diesen Eventstatus aber nicht.

Eventstatus wird nach jedem Update neu berechnet, in dieser Priorität:

1. Ein Step failed ohne allowFailure → failed.
2. Ein erforderlicher Step cancelled → cancelled.
3. Mindestens ein Step running → running.
4. Alle erforderlichen Steps in einem Endzustand → success.
5. Sonst → waiting.

timed_out wird vom Server gesetzt und hat Vorrang vor späteren Ergebnissen. Normales PATCH /v1/event/{id} darf bei Pipeline-Events weder status noch Event-actions ändern. Bestehende Event-Actions lassen sich dort nicht ausführen; definiere interaktive Aktionen direkt am Step. Severity (logLevel) ist unabhängig vom Pipeline-Status. Ein Step-Fehler ändert den Event-Level nicht automatisch und sendet keinen zusätzlichen Fehler-Push.

Step-Actions und Inputs

POST /v1/event/{eventId}/steps/{stepId}/actions/{actionIndex}/execute, Access-JWT, Index ab 0. Body wie bei Event-Actions:

{
  "inputs": {
    "comment": "Freigegeben"
  },
  "confirmed": true
}

Steps verwenden exakt dasselbe Action-Schema: Buttons, Formulare, Links, Webhooks, Notifications, Input-Validierung, Platzhalter, Webhook-Response-Erwartungen, Bestätigung, Ablaufzeit, maxRuns, stopOnFailure und allowRetryOnFailure. Siehe Actions und Formulare. Alle Inputs werden vor der Reservierung validiert. Pro Step ist nur eine Action gleichzeitig möglich; unabhängige Steps können parallel ausgeführt werden.

Ein gestarteter Button oder ein abgesendetes Formular setzt den Step auf running; alle Teilschritte erfolgreich → success, sonst failed. Bei Fehler mit allowRetryOnFailure wird der verbrauchte Run wieder freigegeben. Ein weiterer Versuch benötigt weiterhin erfüllte Abhängigkeiten und darf keine bereits gestarteten Nachfolger invalidieren. Erfolgreich abgeschlossene Steps können nicht erneut ausgeführt werden, auch wenn maxRuns weitere Läufe zuließe.

Für alternative Entscheidungen wie „Annehmen“/„Ablehnen“ einen einzelnen Step mit zwei Actions verwenden: Die erste erfolgreiche Action schließt den Step ab und sperrt die andere. Zwei erforderliche Steps würden dagegen beide Entscheidungen verlangen. Reine Links ändern keinen Stepstatus; ihr Zielprozess muss das Ergebnis bei Bedarf über /step melden.

Timeout und Alert-Zustellung

pipeline.timeout ist eine optionale Ganzzahl in Sekunden (1–31.536.000). Die Frist beginnt mit der Server-Erstellung, unabhängig von einem vom Client gesetzten Event-Zeitstempel. Sie läuft während Warten auf Eingaben und Vorgänger weiter. Deadline und Alert-ID liegen dauerhaft in MongoDB; Neustarts verlieren sie nicht.

Der bestehende Scheduler prüft beim API-Start und alle zehn Sekunden. Aktive Eventzustände waiting/running mit überschrittener Frist wechseln atomar nach timed_out; success, failed und cancelled werden nicht nachträglich wegen Inaktivität zu Timeouts. Nach der ursprünglichen Frist kann eine abgeschlossene Pipeline nicht wieder geöffnet werden. Ohne laufende API findet die Verarbeitung beim nächsten Start statt. Step-Updates prüfen die Frist zusätzlich direkt. Noch wartende oder laufende Steps erhalten beim Timeout den Zustand cancelled und einen Endzeitpunkt. Laufende externe Jobs/Webhooks werden dadurch nicht abgebrochen.

Der Timeout legt ein separates Event im selben Projekt und Kanal an, mit Status failed, tags.reason: pipeline_timeout und tags.pipelineEventId als Verweis auf das ursprüngliche Event. Dessen ID ist auch als pipeline.timeoutAlertId abrufbar. Stabile Alert-ID und atomare Reservierungen verhindern doppelte Alert-Events bei mehreren API-Prozessen.

timeoutAlert.logLevel erlaubt info, warning, failed, critical; Standard failed. Ohne explizites notify gilt dieselbe Voreinstellung wie für andere Events: false bei info/warning, true bei failed/critical. notify: false unterdrückt Push ausdrücklich. Die Einstellungen des ursprünglichen Events (notify, logLevel) sind davon unabhängig. Kanal-Mutes bleiben wirksam. Critical-Push verwendet den vorhandenen Critical-Alert-Pfad.

Die Zustellung nutzt eine zweiminütige Lease. Gemeldete Pushfehler werden erneut versucht. Ein Crash nach Versand und vor Bestätigung oder ein Teilerfolg kann Pushs erneut zustellen; exakt einmalige Pushzustellung wird nicht versprochen. Fehlende oder stummgeschaltete Empfänger gelten als abgeschlossener Versandversuch; bei späterer Aktivierung werden alte Timeouts nicht nachgesendet.

Fehler, Parallelität und Betriebsgrenzen

• 400: ungültige Felder, doppelte IDs, fehlende Referenzen oder Zyklus. Keine Teiländerung am Event.
• 401/403: fehlende Authentifizierung oder kein Projektzugriff.
• 404: Event oder Step fehlt.
• 409: Vorgänger nicht erfüllt, unzulässiger Zustandswechsel, geschlossene Pipeline, aktive Action oder konkurrierende Updates. Zustand erneut lesen und fachlich prüfen, bevor erneut gesendet wird.

Step-Schreibvorgänge verwenden Compare-and-swap über pipeline.revision mit begrenzten Wiederholungen. Parallel abgeschlossene Steps und zusätzliche Logs bleiben erhalten. Externe Webhooks werden erst nach erfolgreicher Reservierung aufgerufen. Bei Verbindungsabbruch während einer Action ist deren fachliches Ergebnis eventuell unbekannt; Webhook-Empfänger sollten eigene Idempotenzschlüssel verwenden. Tracklytic bietet keinen automatischen Replay externer Seiteneffekte. Ein bei Prozessabbruch hängen gebliebener Action-Step bleibt ohne konfigurierten Pipeline-Timeout zur Untersuchung stehen.

Bestehende Events benötigen keine Migration. Die neuen MongoDB-Indizes werden mit dem üblichen Modell-Indexaufbau angelegt. Für schnelles Timeout-Scanning ist der Index auf pipeline.deadline/status relevant.