aggrega push-artifact
Ein eigenständiges Datenartefakt (etwa ein Dokumentationsbündel) in einer OCI-Registry veröffentlichen
Übersicht
aggrega push-artifact <file> [flags]Beschreibung
Publish a standalone data artifact — a documentation bundle or any other non-entity blob — to an OCI registry under the reserved docs/ namespace. Unlike push, which bundles a catalog entity and dispatches on its kind, push-artifact carries opaque bytes: it reads the file, packs it under the given media type (defaulting to the documentation-bundle media type), and tags it at docs/<name>:<tag>. The published artifact is signed separately by reference with aggrega sign. Beside it, push-artifact states when it published, as a small published-at attachment carrying this machine's clock in UTC to the second; the attachment moves no digest and changes no tag.Flags
| Flag | Standard | Beschreibung |
|---|---|---|
--dry-run | false | Berechnet die Referenz und gibt die vorgeschlagene |
--media-type | application/vnd.aggrega.docs.v1beta1+tar+gz | Medientyp des OCI-Artefakts; Standard ist der Medientyp des Dokumentationsbündels |
--name | — | Artefaktname innerhalb des reservierten Namensraums docs/ (z. B. veröffentlicht „aggrega-docs“ unter docs/aggrega-docs) |
--registry | — | Host der Ziel-Registry (überschreibt die default_registry des Workspace) |
--tag | — | Versions-Tag, unter dem das Artefakt veröffentlicht wird (erforderlich) |
Das Dokumentationsbündel-Artefakt
Ein Dokumentationsbündel ist ein eigenständiges Datenartefakt – ein mit gzip komprimiertes tar gerenderter Dokumentation – und keine Katalogentität. Es trägt den Medientyp application/vnd.aggrega.docs.v1beta1+tar+gz, den Artefakttyp, den ein Konsument sieht, wenn er das Bündel aus der Registry abruft.
Bündel werden unter dem Repository-Segment docs/ veröffentlicht: --name aggrega-docs legt das Artefakt unter docs/aggrega-docs ab, und --tag wählt die Version, sodass die Pull-Koordinate <registry>/docs/<name>:<tag> lautet – zum Beispiel hub.aggrega.ai/docs/aggrega-docs:1.0.0. Da das Bündel ein einfaches Datenartefakt und keine Katalogentität ist, wird es mit jedem OCI-kompatiblen Client über diese Referenz und diesen Medientyp abgerufen. Die veröffentlichte Datei trägt den mit --name angegebenen Namen, sodass ein Client, der Dateien nach Namen schreibt, sie unter diesem Namen schreibt: oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 hinterlässt aggrega-docs im aktuellen Verzeichnis, Byte für Byte so, wie es veröffentlicht wurde.
Wenn die Registry einen Schreibvorgang fehlschlagen lässt
Die Veröffentlichung schreibt in Schritten in die Registry – die Datei, das Manifest, das sie benennt, den Tag und dann das Veröffentlichungsdatum daneben –, und jeder dieser Schreibvorgänge wird wiederholt, wenn die Registry oder das Netzwerk ihn auf eine Weise scheitern lässt, bei der ein späterer Versuch gelingen kann, etwa ein Serverfehler, ein Timeout oder eine zurückgesetzte Verbindung; aggrega push listet diese Fehler auf. Ein Schreibvorgang wird höchstens dreimal versucht, im Abstand von einer halben und dann einer ganzen Sekunde, und jeder Versuch ist ein neuer Upload derselben Bytes statt eines erneuten Sendens der fehlgeschlagenen Anfrage, sodass ein wiederholter Schreibvorgang das ablegt, was ein einzelner Versuch abgelegt hätte.
Ein Schreibvorgang, der auch nach seinem letzten Versuch scheitert, lässt den Befehl scheitern, und der Fehler nennt den Schritt. Ein Fehler beim Anhängen des Datums tritt erst auf, nachdem das Artefakt abgelegt wurde: Das Artefakt bleibt veröffentlicht, und der Befehl beendet sich mit einem Exit-Code ungleich null und meldet, dass sein Veröffentlichungsdatum nicht angehängt werden konnte. Wird dieselbe Veröffentlichung erneut ausgeführt, wird sie abgeschlossen: Das Artefakt wird als bereits veröffentlicht gemeldet, nichts wird hochgeladen, und das Datum wird dort angehängt, wo das Artefakt keines trägt, und gibt die Uhrzeit dieses Laufs an – den Zeitpunkt, zu dem die Veröffentlichung abgeschlossen wurde. An ein Artefakt, das bereits ein Datum angibt, wird nichts angehängt, und eine Auflistung, die nicht gelesen werden kann, beendet sich mit einem Exit-Code ungleich null, ohne etwas anzuhängen.
Offline
Das Veröffentlichen eines Artefakts ist ein Netzwerk-Roundtrip, daher verweigert dieser Befehl im Offline-Modus – dem Schlüssel offline auf oberster Ebene einer Konfigurationsdatei, AGGREGA_OFFLINE oder --offline – die Ausführung, bevor er die Datei liest, und die Verweigerung nennt, welche dieser drei Stellen den Modus gesetzt hat. --dry-run funktioniert weiterhin, weil es die Referenz berechnet und keinen Aufruf durchführt. Um für einen einzelnen Lauf aus einem Offline-Workspace zu veröffentlichen, übergeben Sie --offline=false.
Siehe auch
- ./aggrega-sign.md – ein Datenartefakt wird nachträglich per Referenz signiert; dieser Befehl hängt keine eigene Signatur an.
- ./aggrega-serve.md – der Daemon bietet dieselbe Veröffentlichung unter
aggrega/publishArtifact, sodass ein Editor sie ausführen kann, ohne die Sitzung zu verlassen. - ./aggrega-mcp.md – dieselbe Fähigkeit als Werkzeug
publish-artifact, das ein Assistent aufrufen kann. Lesen Sie, was diese Seite über das Zulassen sagt, bevor Sie es tun.