Entwickeln und deployen

Die kanonische Kette von der Spec bis zur installierten Änderung: Workspace-Release, Block-Release ohne Specs, Push, Pull aller Instanzen, Install. Gates, Nicht-Gates und die MCP-Ops zu jedem Schritt.

Diese Seite ist die Prozesskarte für Änderungen an Polycrate-Workspaces und -Blocks: von der Spec bis zur installierten Änderung im Zielsystem. Sie ist die MCP-Sicht auf den CANONICAL FLOW aus polycrate spec manual; die Konzepte dahinter erklärt Spec-Driven Development.

Polycrate versioniert *.poly-Dateien, führt Actions aus und installiert Blocks. Git ist kein Bestandteil des Prozesses.

Die Kette

# Schritt CLI MCP (polycrate mcp) Hard Fail wenn
1 Spec done spec update <id> --set status=done sdd op update_meta (status=done) struktureller Drift; ## Open Questions nicht leer
2 Workspace-Release anlegen release create X.Y.Z [--spec <id>…] workspace op release_create zugewiesene Spec nicht done/cancelled
3 Changelog + Release Note release update X.Y.Z --set type= --set message= --changelog-item --note-section highlights= workspace op release_update —
4 Workspace finalisieren release finalize X.Y.Z workspace op release_finalize message leer; highlights leer; Drift oder Open Questions in zugewiesener Spec; pre_action schlägt fehl
5 Block-Changelog release --block <name> update X.Y.Z --set type= --set message= --changelog-item [--set app_version=] block op release_update kein Feld übergeben
6 Block finalisieren + pushen release block-finalize <name> X.Y.Z [--app-version] [--no-push] block op release_finalize Changelog-Eintrag fehlt oder message/description leer; app_version leer, obwohl block.poly eines führt
7 Downstream konsumieren block pull <registry/org/name>:X.Y.Z block op pull (Version Pflicht) Version fehlt
8 Installieren run <block> install action op run Action schlägt fehl

Schritte 1–4 sind der Workspace-Teil, 5–6 der Block-Teil, 7–8 der Deploy-Teil. Wer nur einen Block ändert, beginnt bei 5 (bei Logikänderung mit einer Workspace-Spec, Label block:<name>, Schritt 1). Wer nur den Workspace released, endet bei 4.

--workspace / -w muss absolut sein. Relativ (., .., ./ws) ist ein Hard Fail — ohne -w gilt das aktuelle Verzeichnis.

Vollständiges Beispiel

Ein Block hardening im Workspace ayedo-core bekommt eine Logikänderung; der Workspace vivavis-prod-paz konsumiert sie.

CORE=/home/me/.polycrate/workspaces/ayedo/ayedo-core
PROD=/home/me/.polycrate/workspaces/vivavis/vivavis-prod-paz

# 1. Spec im Host-Workspace (Label verbindet sie mit dem Block)
polycrate spec create --name "OpenSSH PerSourcePenalties konfigurierbar" --type fix -w $CORE
polycrate spec update 12 --add-label block:hardening -w $CORE
# … Spec schreiben, Block implementieren, spec lint/verify …
polycrate spec update 12 --set status=done -w $CORE

# 5–6. Block-Release (kein release create, keine Block-Spec)
polycrate release --block hardening update 0.5.6 --set type=fix \
  --set message="Konfigurierbare PerSourcePenalties" \
  --changelog-item "Fix: exempt list für PerSourcePenalties" -w $CORE
polycrate release block-finalize hardening 0.5.6 -w $CORE   # setzt block.poly version, pusht

# 2–4. Workspace-Release des Host-Workspaces (optional, wenn der Workspace selbst eine Version führt)
polycrate release create 2.3.0 --spec 12 -w $CORE
polycrate release update 2.3.0 --set type=fix --set message="hardening 0.5.6" \
  --changelog-item "hardening 0.5.6: PerSourcePenalties" \
  --note-section highlights="- hardening 0.5.6" -w $CORE
polycrate release finalize 2.3.0 -w $CORE

# 7–8. Downstream
polycrate block pull cargo.ayedo.cloud/ayedo/linux/hardening:0.5.6 -w $PROD   # schreibt from: auf alle Instanzen
polycrate run hardening install -w $PROD

Ein reiner Versions-Bump des Blocks (Dependency, Image-Tag, kein Verhaltensunterschied) braucht keine Spec: nur Schritte 5–6.

Was passiert bei finalize

Workspace (release finalize): prüft die Gates aus Schritt 4, setzt workspace.poly → version, führt config.release.pre_actions aus, dann post_actions (z. B. Build, Image-Push, Hub-Upload). Kein Git-Tag, kein Commit.

Block (release block-finalize = release --block <name> finalize): prüft die Gates aus Schritt 6, setzt block.poly → version (und app_version, wenn übergeben), validiert, pusht in die Registry. Idempotent: existiert das Tag bereits, wird der Push übersprungen (--force pusht erneut, --no-push lässt ihn aus — dann später block push <name>).

Pull (block pull <fqbn>:<version>): lädt den Block und schreibt from: auf jede Instanz dieses FQBN in workspace.poly. image_tag wird weder geschrieben noch geprüft.

Gates und Nicht-Gates

Hard Fail (Exit ≠ 0): relatives -w; ungültige IDs; H1/H2 in einem Sektionskörper; struktureller Drift bei status=done und bei Workspace-finalize zugewiesener Specs; nicht-leere Open Questions ebenda; release create/update --spec mit einer Spec, die nicht done/cancelled ist; leere Changelog-message; leere highlights; Block-finalize ohne Changelog-Eintrag oder mit leerem message/description; fehlendes app_version, wenn block.poly eines führt; block pull ohne Version.

--force (mit --force-reason, auditiert in .specs/.force-audit.log): umgeht bei status=done Drift und Open Questions; bei release finalize nur highlights.

Kein Gate (Warnung oder stumm): rotes spec verify, fehlendes spec review, unerfüllte needs:, 0 Specs an einem Release, Dirty Git Tree, existierendes Git-Tag vX.Y.Z, ungepushte Commits.

MCP

Ein Server: polycrate mcp. Sechs Tools, dispatcht über op. Keine Aliase, keine session_id. Mutierende Ops brauchen workspace als absoluten Pfad.

Tool Ops
sdd list inspect create update_meta update_section lint format
docs schema (workspace/block/changelog/secrets, lokal) · guide (eingebettet) · get search (ayedo.de Public API)
hub inspect_block list_versions list_blocks info cli_latest_version cli_list_versions cli_artifacts
workspace release_create release_update release_finalize release_status
block release_update release_finalize release_status push pull verify — kein release_create (Fehler mit Hinweis)
action run

sdd.update_section schreibt nur Sektionskörper (kein H1/H2, kein Frontmatter). Direkte Datei-Edits der Sektionskörper bleiben erlaubt; beide Wege enden in lint. docs op guide mit name=dev_and_deploy liefert diese Kette als eingebetteten Text; polycrate spec manual bleibt die SSOT.

Konfiguration und Troubleshooting: MCP Server.

Docker-Registry-Auth

~/.docker/config.json wird nicht gemountet. Credentials kommen aus der Prozessumgebung in den Action-Container:

  • DOCKER_REGISTRY_HOST
  • DOCKER_REGISTRY_USER
  • DOCKER_REGISTRY_PASSWORD

CARGO_* ist nur Playbook-Fallback.

Was Polycrate nicht als Prozess vorgibt

  • Git-Tag als Source of Truth — released ist: Changelog-Eintrag + Versionsdatei (Workspace) bzw. Registry-Tag (Block)
  • workspace sync oder git commit/tag/push als Release-Schritt
  • block bump — existiert nicht; block-finalize setzt die Version
  • Block-Specs — Blocks haben kein .specs/
  • CI-first — CI konsumiert dieselbe Kette
  • image_tag als Produktprüfung

Versionskontrolle bleibt Ihre Gewohnheit, nicht der Polycrate-Prozess — siehe Git-Integration.

Weiter