Publishing-Kanäle

Publishing-Kanäle pushen oder stellen Dokumentinhalte an externe Systeme bereit, wenn sich Dokumente ändern — ergänzend zu Webhooks (die über Ereignisse benachrichtigen) und Export (manuelle einmalige Downloads).

Voraussetzungen

• Capability Publishing (oder Team-Admin)
• Server-Env: PUBLISHING_ENCRYPTION_KEY (siehe Installation)
• Für Git-Mirrors: optional GIT_MIRROR_ALLOWED_HOSTS für Nicht-Standard-Hosts

Zugriff

Einstellungen → Publishing — Liste der Kanäle, Zustellungsprotokoll, Assistent zum Anlegen/Bearbeiten.

Transport-Typen

Transport	Funktionsweise	Ideal für
Pull	Consumer holt Inhalte selbst über die token-gesicherte Pull-API ab (Bearer-Token)	Static Sites, SSR-Apps, einfache Integrationen
Webhook	Orimora POSTet die Dokument-Payload bei Änderung an deine URL	CMS-Updates, eigene Pipelines
Git-Mirror	Orimora committet/pusht Markdown in ein Git-Repository	Docs-Sites (GitHub Pages, GitLab CI)

Scope

Jeder Kanal adressiert Inhalte über:

• Collection — ein Ordner und seine Dokumente
• Tag — alle Dokumente mit einem bestimmten Tag

Du musst explizit eine Collection oder einen Tag wählen (kein „gesamter Workspace”-Wildcard).

Format

Format	Beschreibung
markdown	Markdown-Dateien (Standard für Git-Mirror)
json	TipTap-JSON
html	Gerendertes HTML (wo unterstützt)

Pull-Kanal einrichten

1. Kanal anlegen → Transport Pull, Format Markdown. Optional eine Deploy-Hook-URL eintragen (siehe unten).
2. Dokumente an den Kanal publizieren per „An Kanal senden…” — die Pull-API liefert genau dieses kuratierte Set (nie ein unpubliziertes Dokument)
3. Ein Token am Kanal erstellen — behandle es wie ein Passwort
4. Dein Consumer ruft periodisch oder zur Build-Zeit ab. Die fertige Pull-API-URL steht auf der Kanal-Karte und lässt sich dort kopieren.

Hinweis

Wofür ist das Token — und wofür nicht? Das Token braucht ausschließlich der Consumer (das System, das die Pull-API abruft). Das Publizieren selbst — „An Kanal senden…” — läuft über deine Login-Session und braucht kein Token. Ein Kanal ohne Token ist trotzdem eine Sackgasse: niemand kann abrufen. Die UI warnt beim Publizieren, wenn das der Fall ist.

Deploy-Hook: statische Seiten automatisch neu bauen

Statische Generatoren (Starlight, Hugo, Astro …) übernehmen neue Inhalte erst beim nächsten Build. Trage am Pull-Kanal die Build-Hook-URL deines Hosts ein, dann POSTet Orimora nach jedem Publizieren dorthin und der Rebuild startet automatisch:

• Netlify: Site configuration → Build & deploy → Build hooks
• Vercel: Project → Settings → Git → Deploy Hooks
• Cloudflare Pages: Settings → Builds & deployments → Deploy hooks
• Coolify: POST /api/v1/deploy?uuid=<app-uuid> — verlangt zusätzlich einen Authorization-Header (Bearer <api-token>); dafür gibt es am Kanal das optionale Header-Feld unter der Hook-URL

Server-gerenderte Consumer (SSR/ISR) brauchen keinen Hook — sie holen Inhalte zur Laufzeit ab. Der Hook ist Best-Effort: Schlägt er fehl, bleibt das Publizieren trotzdem erfolgreich; der Fehler erscheint am Kanal.

Woran erkenne ich, dass es geklappt hat?

Ein Pull-Kanal erzeugt beim Publizieren bewusst keine Zustellung — der Inhalt wird erst sichtbar, wenn ein Consumer ihn abruft. Drei Signale zeigen den Erfolg:

1. Direkt nach dem Publizieren: Der Dialog bestätigt „Inhalte stehen über die Pull-API bereit” (und ob der Deploy-Hook ausgelöst wurde).

2. „Zuletzt abgerufen” auf der Kanal-Karte: stempelt jeden authentifizierten Pull-API-Abruf — die ehrliche End-to-End-Bestätigung.

3. Manuell per curl (Werte von der Kanal-Karte):

   curl -H "Authorization: Bearer <token>" \
     "https://deine-instanz.example/api/v1/published/<kanal-id>/documents"

   Du musst deine publizierten Dokumente als JSON sehen.

Webhook-Transport einrichten

Ähnlich zu Webhooks, sendet aber Dokument-Payloads zum Publizieren statt generischer Event-Umschläge. Konfiguriere URL und optionales Signatur-Geheimnis. Fehlgeschlagene Zustellungen können den Kanal automatisch pausieren (PUBLISHING_CHANNEL_*-Env-Vars).

Git-Mirror einrichten

1. Transport Git-Mirror
2. Repository-URL (GitHub, GitLab, Bitbucket, Gitea, Codeberg standardmäßig unterstützt)
3. Branch und optionales Pfad-Präfix
4. Credentials angeben (PAT oder Deploy Key) — verschlüsselt gespeichert

Orimora pusht Markdown bei Dokumentänderungen. Stelle sicher, dass das Token Push-Zugriff auf den Ziel-Branch hat.

Achtung

Git-Mirror-Fehler (Auth, Branch Protection) pausieren den Kanal schneller als generische Webhooks — prüfe das Zustellungsprotokoll in den Einstellungen.

Zustellungsprotokoll

Webhook- und Git-Mirror-Kanäle zeigen aktuelle Zustellungen: Status, HTTP-Code, Dauer, Fehlermeldung. Damit debuggst du fehlgeschlagene Pushes oder Webhook-Antworten. Pull-Kanäle haben prinzipbedingt keine Zustellungen — dort gilt stattdessen „Zuletzt abgerufen” auf der Kanal-Karte (siehe oben).

Vergleich: Webhooks vs. Publishing

Funktion	Entwickler → Webhooks	Einstellungen → Publishing
Zweck	Event-Benachrichtigungen	Inhalts-Sync
Payload	Event-Umschlag + Model-Snapshot	Dokumentinhalt im gewählten Format
Transports	Nur HTTP POST	Pull, Webhook, Git-Mirror
Scope	Pro Event-Abonnement	Pro Collection oder Tag

Siehe auch

• Webhooks — ereignisgesteuerte Automatisierung
• Export — manueller Download
• Konfiguration — PUBLISHING_* und GIT_MIRROR_ALLOWED_HOSTS
• Berechtigungen & Gruppen — Capability Publishing