Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

aggrega push

aggrega push veröffentlicht eine Katalogentität in einer OCI-Registry, wo andere Workspaces sie mit aggrega pull auflösen können.

Funktionsweise

aggrega push liest eine einzelne Entitäts-YAML, bündelt sie für den Transport und überträgt sie nach <registry>/<kind>/<metadata.name>:<metadata.version>, wobei der Repository-Pfad in Kleinbuchstaben umgewandelt wird; ein Recipe oder FeatureRecipe trägt seine spec.capability und ein Plugin seinen metadata.pluginType als Segment zwischen Art und Name. Führen Sie aggrega push --list-kinds aus, um die Entitätsarten zu erhalten, die das installierte Binary veröffentlicht – eine Art pro Zeile, sortiert und sonst nichts, sodass ein Skript die Ausgabe direkt lesen kann. Die Menge umfasst die Arten für das Katalog-Authoring zusammen mit dem Aggregate, einem wiederverwendbaren Modul, und dem Plugin, einer inhaltsadressierten Referenz auf ein WebAssembly-Artefakt, das der Compiler weiterleitet und die Laufzeitumgebung ausführt. Das Plugin ist ein strukturelles veröffentlichbares Artefakt und keine Art für das Katalog-Authoring. Veröffentlichbarkeit ist eine Eigenschaft der Entität, nicht ihrer Verwendung: Ein Aggregate ist veröffentlichbar, ob es später als spec.aggregate auf oberster Ebene eines Release referenziert oder im aggregates:-Block eines anderen Aggregate verschachtelt wird. Release und Manifest sind Eingaben auf der Deployment-Seite, keine Katalogartefakte, und werden abgelehnt.

Bündelung

Ein Push veröffentlicht das Entitätsdokument und die Dateien, die die Entität selbst daneben nennt – und sonst nichts in ihrem Verzeichnis. Die Dateien, die eine Entität nennt, sind:

  • für ein Recipe oder FeatureRecipe seine lokale source: – ein Verzeichnis wird mit jeder Datei darunter übertragen, die die in seiner entity.lock aufgezeichneten Ignorierregeln behalten, wie Welche Dateien mit einer Entität ausgeliefert werden beschreibt; jede Datei, die seine Einträge valuesMapping:, workload: und artifacts: mit $import: importieren; und die entity.lock daneben;
  • für eine Component oder ein Feature jede Schemadatei, die ihr spec.schema, eine Säule oder ein usesSchema-Socket mit $import: importiert, einschließlich jeder Datei, die eine importierte Datei ihrerseits importiert.

Ein Aggregate, ein Plugin und die Bibliotheksarten nennen keine Datei neben ihrem Dokument. Eine Notiz, eine README, die Dateien einer anderen Entität oder die Ausgabe eines Builds im Verzeichnis werden nicht veröffentlicht, wie auch immer sie heißen. Ein symbolischer Link unter den Dateien, die eine Entität nennt, wird abgelehnt statt verfolgt – A symbolic link sits among the files an entity carries (Ein symbolischer Link befindet sich unter den Dateien, die eine Entität mitführt) –, ebenso ein Pfad, den eine Entität über ein Verzeichnis nennt, das ein aus dem Verzeichnis der Entität hinausführender Link ist, bevor irgendetwas gepackt wird – A path names content outside the entity’s own directory (Ein Pfad nennt Inhalt außerhalb des eigenen Verzeichnisses der Entität).

Daraus ergibt sich die Form. Eine Entität, die nichts nennt, wird als ihr Dokument veröffentlicht, unverändert, unter dem +yaml-Medientyp ihrer Art. Eine, die eine Datei nennt, wird als .tar.gz veröffentlicht, das das Dokument und diese Dateien an ihren Stellen im Verzeichnis enthält, unter dem +tar+gz-Medientyp ihrer Art. Ein Recipe, dessen Inhalt vollständig inline ist, wird also als sein Dokument veröffentlicht, und eine Component, deren Schema aus einer Datei importiert wird, als Archiv. Katalog und Registry §6 listet beide Medientypen für jede Art auf.

Jede Datei in einem Archiv trägt den Modus 0644 und keinen Zeitstempel, unabhängig von ihren Berechtigungsbits auf der Festplatte. Ein Checkout schreibt Dateien mit seinen eigenen Berechtigungsbits, und ein System, das kein Ausführungsbit aufzeichnet, checkt als gewöhnliche Datei aus, was ein anderes System als ausführbar auscheckt; daher trägt das Archiv keinen von der Festplatte gelesenen Modus: Zwei Checkouts desselben Commits veröffentlichen dieselben Dateien, unabhängig von ihrer umask und davon, auf welchem System sie erstellt wurden, und das Umschalten des Ausführungsbits eines Skripts ändert nichts an dem, was veröffentlicht wird.

Ein Push warnt bei jedem Eintrag eines Archivs, den Windows nicht so aufnehmen kann, wie er geschrieben ist – ein Pfad mit einem Bestandteil, der nach einem Gerät benannt ist, etwa CON, AUX oder NUL, in beliebiger Groß- und Kleinschreibung und mit beliebiger Erweiterung, wie aux/x.yaml, oder ein Bestandteil, der auf einen Punkt oder ein Leerzeichen endet, wie report.. Unter Windows verweigert aggrega das Entpacken eines solchen Eintrags, sodass ein Windows-Workspace die Version nicht verwenden kann. Die Warnung wird auf jeder Plattform auf die Standardfehlerausgabe geschrieben, eine Zeile pro Eintrag, vor dem eigenen Bericht der Veröffentlichung; der Dateiname des Entitätsdokuments selbst wird zusammen mit den Dateien beurteilt, die es nennt, und eine Entität, die nichts nennt, wird allein als ihr Dokument veröffentlicht und nie gewarnt. Sie verweigert nichts: Der Push wird genau so ausgeführt oder abgelehnt, wie es ohne sie geschähe, und --dry-run warnt auf dieselbe Weise. A published archive carries an entry Windows cannot use (Ein veröffentlichtes Archiv enthält einen Eintrag, den Windows nicht verwenden kann) zeigt die Zeile und was dagegen zu tun ist.

Eine als Template geschriebene lokale source: führt das gesamte Verzeichnis mit. Ein Template wie ./charts/{{ .values.flavour }} benennt ein Verzeichnis erst, wenn ein Release es ausfüllt, sodass keine Veröffentlichung wissen kann, welches es sein wird. Eine solche Entität führt jede Datei in ihrem eigenen Verzeichnis mit, die ihre aufgezeichneten Ignorierregeln behalten – nie ihre .aggregaignore, deren Regeln innerhalb der Sperre übertragen werden –, und der Push weist unter seinen anderen Angaben darauf hin:

carries: every file in the entity's directory, because its source "./charts/{{ .values.flavour }}" is a template and the directory it names is decided by each Release that uses it

Was nicht benannt ist, wird nicht übertragen, und ein Konsument ist derjenige, der es bemerkt. Eine Datei, auf die sich die Entität verlässt, ohne sie über eines der obigen Felder zu benennen, ist nicht in der Veröffentlichung, und der Build eines Konsumenten scheitert unter Nennung des fehlenden Pfads innerhalb seines Cache-Slots – nicht Ihr Push. Benennen Sie jede Datei, die die Entität braucht, über eines dieser Felder.

Jede veröffentlichte Datei ist im Manifest des Artefakts benannt, sodass ein generischer OCI-Client wie oras sie in eine Datei dieses Namens schreibt: entity.yaml für eine als ihr Dokument veröffentlichte Entität, entity.tar.gz für eine mit ihren Dateien veröffentlichte, und für ein Plugin entity.yaml für die Entität neben entity.wasm für seine ausführbare Datei. Der Name ergibt sich aus dem Medientyp, nicht aus der Datei, aus der Sie veröffentlichen, sodass derselbe Inhalt, aus einer umbenannten Datei veröffentlicht, dasselbe Artefakt ergibt. Katalog und Registry §6 listet jede veröffentlichte Form und die Datei auf, als die sie jeweils ankommt.

Eine entfernte source:-URL in einem Recipe (eine OCI-Chart-Referenz, eine HTTPS-Chart- oder Fragment-URL, ein Git-Modul) wird im veröffentlichten YAML wörtlich beibehalten; sie wird nicht abgerufen und in das Artefakt eingebettet. Konsumenten lösen entfernte Quellen unabhängig zu ihrer eigenen Pull-Zeit auf und pinnen sie. So bleiben die Verteilung von Katalogentitäten und die Auflösung von Quellartefakten getrennte Belange.

Ein Aggregate wird als eigenes einzelnes Dokument veröffentlicht: Ein Unter-Aggregate, das es in aggregates: referenziert, wird nicht in das Artefakt gebündelt. Jedes Unter-Aggregate ist ein separat veröffentlichtes Aggregate, das Konsumenten zur Pull-Zeit unabhängig über seine Identität auflösen und pinnen – dasselbe Prinzip der getrennten Verteilung, das für entfernte Quellen gilt.

Eine Entität pro Verzeichnis

Ein Archiv enthält die Entitätsdatei unter den Dateien, die es benennt, daher muss die Entität beim Entpacken wiedergefunden werden. Ein Konsument findet sie an der Präambel, die sie trägt: Das Dokument oben im Bündel, dessen kind: eine veröffentlichbare Entitätsart ist, ist die Entität. Die Datei, in der sie geschrieben ist, kann beliebig heißen – recipe.yaml ist die Konvention des Katalogs, keine Anforderung –, und ein Compose-Fragment, ein Chart-Template oder ein Kubernetes-Manifest neben der Entität wird nicht für eine gehalten, weil diese etwas anderes oder gar keine Art deklarieren. Entitätsdokumente weiter unten, innerhalb eines source/-Baums, sind Inhalt, den die Entität ausliefert, nicht die Entität selbst, und werden nie berücksichtigt.

Ein Push lehnt eine Entität ab, die ihr Verzeichnis mit einer anderen Entität teilt. Jede Art hat ein eigenes Verzeichnis, außer Aggregate, Release und Manifest, die ein Workspace-Stammverzeichnis nebeneinander enthält. Bei jeder anderen Art prüft ein Push, bevor er irgendetwas anderes mit der Entität tut – vor dem Pin-Schritt, der Signierrichtlinie und dem Bündel –, dass kein anderes Entitätsdokument im selben Verzeichnis liegt, und lehnt andernfalls ab, wobei er jede im Weg stehende Entität nennt, unabhängig davon, ob der Push zum Pinnen aufgefordert wurde. aggrega pin lehnt dasselbe Verzeichnis mit denselben Worten ab; der Abbruch ist An entity shares its directory with another entity (Eine Entität teilt ihr Verzeichnis mit einer anderen Entität). Ein Dokument keiner Entitätsart neben der Entität – eine Chart-Datei, ein Compose-Fragment, eine README – steht nicht im Weg, ebenso wenig irgendetwas in einem Unterverzeichnis. Jedes Dokument neben der Entität wird nur innerhalb des Workspace gelesen oder, bei einer Entität, die Sie außerhalb davon nennen, innerhalb des eigenen Verzeichnisses der Entität, sodass eines, das ein hinausführender Link ist, den Push anhält und den Link ungelesen nennt, wie die Workspace-Grenze darlegt.

Die Regel sorgt dafür, dass eine entity.lock zu einer einzigen Entität gehört: Der Dateiname der Sperre ist für jede Entität derselbe, sodass zwei in einem Verzeichnis geschriebene Entitäten sich die eine Sperre teilen würden, für die dort Platz ist. Sie wird nur beurteilt, wenn etwas aus dem Verzeichnis erzeugt wird, sodass ein Verzeichnis mit mehreren Entitäten weiterhin geladen, gelintet und gebaut werden kann.

Der Name des Verzeichnisses wird nicht beurteilt. Eine Entität, die allein in ihrem Verzeichnis liegt, wird unter ihrer metadata.version veröffentlicht, wo auch immer dieses Verzeichnis liegt; <name>/<version>/, das Layout, dem der Katalog der Standardbibliothek folgt, ist eine Konvention. Ein Artefakt, das ein anderer Client aus einem Verzeichnis mit zwei Entitäten veröffentlicht hat, wird dennoch sicher gelesen: Ein Pull davon hält an und nennt beide Dokumente, statt mit einem davon zu antworten, katalogisiert unter errors/fatal-halts.md.

Die Entität vor dem Bündeln lesen

Ein Push liest eine Component, ein Feature, ein Recipe oder ein FeatureRecipe so, wie ein Build es liest, und lehnt ab, was dieses Lesen ablehnt – aus demselben Grund, unter demselben Kurzcode, bevor das Bündel erstellt und bevor die Ziel-Registry kontaktiert wird. Ein Dokument, das das Schema seiner Art nicht erfüllt, ein Pfad, der Inhalt außerhalb des eigenen Verzeichnisses der Entität nennt, und ein Schema, das eine Component oder ein Feature mit $import: importiert und das fehlt oder nicht verwendet werden kann, werden also bei der Veröffentlichung abgelehnt statt veröffentlicht. Jedes davon ist eine Entität, die der erste Build ihrer Konsumenten ablehnen würde; ein Pfad, der das Verzeichnis verlässt, nennt außerdem eine Datei, die nicht mit der Entität übertragen würde, weil jede Datei, die eine Veröffentlichung mitführt, aus dem eigenen Verzeichnis der Entität stammt – siehe A path names content outside the entity’s own directory (Ein Pfad nennt Inhalt außerhalb des eigenen Verzeichnisses der Entität).

Ein Recipe oder FeatureRecipe wird auf diese Weise gelesen, während seine Pins verglichen werden, wie der nächste Abschnitt beschreibt, sodass das Lesen stattfindet, ob der Push zum Pinnen aufgefordert wird oder nicht und ob die Entität etwas zu pinnen hat oder nicht. Jede der vier Arten wird außerdem unmittelbar vor dem Erstellen ihres Bündels auf diese Weise gelesen, weil dieses Lesen angibt, welche Dateien sie nennt. Ein Aggregate und eine Bibliothek nennen keine Datei und werden nicht auf diese Weise gelesen. Ein Plugin nennt ebenfalls keine Datei und wird gegen das Schema seiner Art gelesen, bevor seine .wasm gelesen wird, wie Ein Plugin veröffentlichen beschreibt.

Ein Plugin veröffentlichen

Ein Plugin wird zusammen mit seiner .wasm veröffentlicht, die mit --plugin angegeben wird, und ein Push beurteilt beide, bevor Bytes veröffentlicht werden oder die Registry kontaktiert wird. --dry-run beurteilt sie genau so wie eine Veröffentlichung.

Die Entität wird zuerst gegen das Schema ihrer Art gelesen, so wie ein Katalog-Ladevorgang sie liest, bevor die .wasm gelesen wird. Eine metadata.version, die keine semantische Version ist – ein bloßer Commit wie 415148e –, wird daher unter der eigenen Bedingung des Schemas abgelehnt, wobei das Feld genannt wird, und ebenso jede andere Abweichung vom Schema, etwa eine fehlende spec.abiVersion. Was hier als semantische Version gilt, ist das eigene Muster des Schemas für metadata.version; der Push fügt keine eigene Regel hinzu.

Dann wird die .wasm geladen und an der Entität gemessen. Was sie nach eigener Angabe anbietet, muss mit dem übereinstimmen, was die Entität beansprucht, der Befehlssatz und die Host-Funktionen, die die Entität aufzeichnet, müssen ihr entsprechen, und die Version, die sie über ihren eigenen Build angibt, muss gleich metadata.version sein – siehe A Plugin entity’s recorded version does not match the plugin (Die aufgezeichnete Version einer Plugin-Entität stimmt nicht mit dem Plugin überein).

Eine .wasm, die aus einem Arbeitsverzeichnis mit nicht committeten Änderungen gebaut wurde, wird abgelehnt. Ein solcher Build trägt die Markierung -dirty am Ende der Version, die er angibt – 1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty. Das ist eine gültige semantische Version, aber sie benennt einen Commit, der nicht enthält, was gebaut wurde, sodass niemand das Veröffentlichte aus der Version, unter der es veröffentlicht wurde, neu bauen könnte. Der Push lehnt sie ab und nennt die Version und die Abhilfe: Bauen Sie das Plugin aus einem sauberen Checkout des Commits, den der Tag des Release benennt, damit es die Release-Version selbst angibt – und um die Änderung zu veröffentlichen, committen Sie sie mit der auf das neue Release gesetzten metadata.version der Entität und versehen Sie diesen Commit zuerst mit dem Tag –, statt die Version, die ein Neubau angibt, in die Entität zu kopieren. Eine aus einem Commit gebaute Entwicklungsversion wie 1.0.0-3-g1a2b3c4 und eine Vorabversion wie 1.0.0-rc.1 werden beide veröffentlicht. Die Ablehnung ist A plugin was built from a working tree with uncommitted changes (Ein Plugin wurde aus einem Arbeitsverzeichnis mit nicht committeten Änderungen gebaut).

Pinnen vor dem Veröffentlichen

Ein Recipe oder FeatureRecipe trägt die Pins für die Eingaben, die es liest — eine vollständig ausgeschriebene entfernte source:, eine Datei, die ein artifacts-Eintrag importiert, die Dateien einer source: daneben — in der entity.lock neben sich, und ein Push veröffentlicht diese Datei mit der Entität. Das Pinnen ist ein Schritt, den Sie vor dem Veröffentlichen ausführen, aggrega pin, und Sie committen die Lock-Datei, die er schreibt.

Ein Push lehnt eine Entität ab, deren Lock diese Pins nicht aufzeichnet. Bevor er das Bundle erstellt, ermittelt ein Push, was der Pin-Schritt für die Entität aufzeichnen würde, und vergleicht es mit der entity.lock daneben. Wo ein Pin fehlt oder das Lock einen enthält, dem eine Eingabe nicht mehr entspricht, stoppt der Push, bevor ein Archiv erstellt oder eine Registry kontaktiert wird. Die Ablehnung nennt die Entität und jede solche Eingabe — jeweils eine remote source, eine imported file oder eine local source file — und was auszuführen ist: aggrega pin für die Entität, --pin-sources für den gerade ausgeführten Push oder pin_sources_at_push für jeden Push im Workspace. Es ist dieselbe Ablehnung, die ein Pull für dasselbe Lock auslöst, An entity reads an input the lock beside it records no pin for (Eine Entität liest eine Eingabe, für die das Lock daneben keinen Pin aufzeichnet), mit den eigenen Abhilfen eines Push. Ein Recipe oder FeatureRecipe, das ein Push veröffentlicht, trägt also in seinem Bundle ein Lock, das jeden Pin aufzeichnet, den der Schritt zum Zeitpunkt der Veröffentlichung aufgezeichnet hätte.

Zwei Arten von Entitäten haben nichts zu pinnen und werden unverändert veröffentlicht: eine Entität, die keine entfernte Quelle liest, keine Datei importiert und keine lokale Quelle nennt, und ein Recipe, dessen Koordinaten der entfernten Quelle aus einem Template ausgefüllt werden. Diese Quelle benennt ein Artefakt erst, wenn ein Release das Template ausfüllt, daher gehört ihr Pin in das Lockfile jedes Release, und ein Push verlangt keinen neben der Entität. Eine Component, ein Feature, eine Bibliothek, ein Aggregate oder ein Plugin liest nichts, was das Lock aufzeichnet, und wird hier nie abgelehnt.

Den Pin einer entfernten Quelle zu vergleichen bedeutet, die Quelle abzurufen, wie es aggrega pin tut, denn ein Pin, der nicht mehr passt, ist nur im Vergleich mit dem sichtbar, was die Quelle jetzt ausliefert. Ein Push für eine Entität mit einer solchen Quelle erreicht daher den Host der Quelle, bevor er die Registry erreicht. Der Vergleich liest ein Recipe oder FeatureRecipe so, wie es der Pin-Schritt tut, über den Katalog, sodass eines, das der Katalog nicht lesen will — etwa ein Dokument, das am Schema seiner Art scheitert —, hier mit der eigenen Begründung des Katalogs abgelehnt wird.

Wo kein Workspace gefunden und keiner benannt wurde, wird ein Push, der für den Vergleich eine entfernte Quelle abrufen würde, vor dem Abruf abgelehnt, wie bei aggrega pin. Der Vergleich ruft jede entfernte Quelle, die die Entität vollständig ausschreibt, in den Artefakt-Cache ab, genau wie der Pin-Schritt, und ein Cache, der in einen Ordner geschrieben wird, von dem aus kein Workspace gefunden wurde, würde diesen Ordner zu einem Workspace machen. Wenn also nichts ein Stammverzeichnis benennt und nichts eines verankert — vom Ordner aus, in dem Sie den Push ausführen, oder, bei einer über einen absoluten Pfad benannten Entität, vom eigenen Ordner der Entität aus —, stoppt ein Push eines Recipe oder FeatureRecipe mit einer solchen Quelle, bevor die Quelle abgerufen wird, einschließlich eines Probelaufs und --pin-sources, und nennt die Quelle, den Ordner und die beiden Lösungen: Benennen Sie Ihren Workspace mit --workspace-root oder AGGREGA_WORKSPACE_ROOT, oder geben Sie diesem Ordner eine .aggrega-config.yaml mit einem workspace:-Block. Für die beiden oben genannten Arten von Entitäten ruft der Vergleich nichts ab, ebenso wenig für eine, deren Quelle lokal ist, sodass jede davon mit ihrem Lock verglichen und dort wie überall veröffentlicht wird; und jede andere Art ist an kein Lock gebunden und wird deshalb nicht abgelehnt. Konfiguration listet die anderen Befehle auf, für die dies gilt.

aggrega push --pin-sources führt denselben Schritt zuerst für Sie aus. Der Schritt läuft, bevor das Bundle erstellt wird, sodass das geschriebene Lock im veröffentlichten Artefakt enthalten ist und der veröffentlichte Digest es abdeckt; und er läuft vor jeder anderen Ablehnung, die die Entität beurteilt, sodass die gepinnte Entität beurteilt wird. Nur die oben beschriebene Verzeichnisregel kommt zuerst, weil der Schritt das eine Lock schreibt, das das Verzeichnis enthält. Er schreibt dieselben Bytes, die aggrega pin schreibt, sodass die obige Ablehnung bei diesem Lauf nie auslöst: Das gerade vom Schritt geschriebene Lock zeichnet genau das auf, womit die Ablehnung vergleichen würde. Der Workspace-Schlüssel pin_sources_at_push macht dies zum Standard jedes Push, und --pin-sources=false überspringt den Schritt für einen Lauf, wodurch die Ablehnung zurückkehrt. Der Schritt schreibt neben die Entität, was einen beschreibbaren Ort erfordert — und ein Push hat immer einen, da er das von Ihnen benannte Dokument veröffentlicht.

--dry-run antwortet so, wie die Veröffentlichung antworten würde. Ohne --pin-sources lehnt er eine ungepinnte Entität genau wie die Veröffentlichung ab, sodass ein Probelauf, der ein Bundle meldet, einer ist, den diese Ablehnung durchlassen würde. Mit --pin-sources pinnt der Schritt als Probelauf: Er gibt das Lock aus, das er schreiben würde, und schreibt nichts, und die folgenden Bundle-Angaben beschreiben das Verzeichnis, wie es ist, ohne dieses Lock — der Digest ist also der einer Veröffentlichung ohne es, und wo das Lock neu wäre, gilt das auch für die Größe und, bei einer Entität, die sonst nichts benennt, für den Medientyp. Die Ablehnung löst nicht aus, weil die Veröffentlichung zuerst gepinnt hätte.

Best Practice: Eine Änderung an einer bereits veröffentlichten Version gehört in eine neue Version und danach in einen Pin. Kopieren Sie die Entität in ein neues Versionsverzeichnis, nehmen Sie die Änderung dort vor, pinnen Sie sie und veröffentlichen Sie diese. Die Hälfte davon, die das Produkt durchsetzt, ist der nächste Abschnitt: Unterschiedliche Inhalte unter einer bereits veröffentlichten Version zu veröffentlichen, wird abgelehnt. Die andere Hälfte — eine bereits veröffentlichte Version nach einer Bearbeitung im eigenen Workspace nicht erneut zu pinnen — liegt bei Ihnen; lokal lehnt nichts sie ab, weil erneutes Pinnen für eine Entität, die Sie nicht veröffentlicht haben, legitim ist.

Registry, Tag und inhaltsbasierte Adressierung

Die Ziel-Registry ist --registry <ref>, sofern angegeben, andernfalls die default_registry des Workspace (standardmäßig hub.aggrega.ai). Der Tag ist die metadata.version der Entität, und der Repository-Pfad wird aus ihrer Art und ihrem Namen abgeleitet, sodass der Ort, an dem eine veröffentlichte Version landet, nicht vom Verzeichnis abhängt, aus dem sie veröffentlicht wurde.

Eine default_registry kann einen Repository-Pfad enthalten, und eine Veröffentlichung darüber landet unter diesem Pfad. Mit default_registry: ghcr.io/acme wird die Component core/api-server in Version 1.0.0 unter ghcr.io/acme/component/core/api-server:1.0.0 veröffentlicht — dem Ort, von dem ein Pull über denselben Standard sie abruft, sodass die hier angehängte Signatur diejenige ist, die dieser Pull findet. --registry benennt einen Host, und eine damit gelenkte Veröffentlichung landet ohne Pfad auf diesem Host. Wie auch immer das Ziel benannt wird, die geltende Signaturanforderung und Signaturkonfiguration sind die für seinen Host hinterlegten: Ein Pfad wählt nie eine andere Richtlinie. Die Schreibweise eines Pfads wird unter wie ein Registry-Host geschrieben wird erläutert.

Das Manifest nennt den Digest der veröffentlichten Bytes, und das Lockfile zeichnet den Digest dessen auf, was sie enthalten. Das OCI-Manifest, das ein Push schreibt, nennt den Digest des veröffentlichten Dokuments oder Archivs, und aggrega pull lehnt einen Download ab, der nicht dazu passt, sodass zwischen Veröffentlichung und Pull veränderte Bytes erkannt werden. Das Lockfile, das ein Pull schreibt, zeichnet die Entität mit einem anderen Digest auf: dem Digest ihres Inhalts — Pfad und Bytes jeder Datei, und nichts darüber, wie das Archiv komprimiert wurde oder welche Berechtigungsbits seine Dateien hatten. Das ist der Digest, den ein Pull im eigenen Workspace des Autors für dieselbe Entität in seinem Katalogverzeichnis aufzeichnet, sodass ein Autor und jeder Konsument einer Veröffentlichung denselben Wert aufzeichnen und ein Build auf beiden Seiten Inhalte ablehnt, die nicht mehr dazu passen. Die beiden Digests beantworten unterschiedliche Fragen: Der des Manifests prüft den Download, und der des Lockfile ist die Identität der Entität.

Veröffentlichen über eine vorhandene Version

Bevor Bytes hochgeladen werden, ermittelt aggrega push, was die Ziel-Registry unter der Referenz, die er gleich schreiben wird, bereits enthält, und vergleicht es mit dem vorliegenden Inhalt. Drei Ergebnisse:

  • Dort ist noch nichts veröffentlicht — der Push fährt fort und veröffentlicht normal.
  • Derselbe Inhalt — nichts wird hochgeladen, und der Befehl meldet die Version als bereits veröffentlicht, sodass ein wiederholter oder erneut versuchter Push kein Fehler ist. Was ein früherer Push nicht angehängt hat — die Signatur oder das Veröffentlichungsdatum —, wird jetzt angehängt, wie unter Eine von einem früheren Push unvollständig gelassene Veröffentlichung abschließen beschrieben.
  • Anderer Inhalt — der Push hält an und nennt den bereits veröffentlichten Digest und den, den er geschrieben hätte. Kein Flag erzwingt ihn.

Eine bereits veröffentlichte Version bezeichnet daher weiterhin die darunter veröffentlichten Bytes. Geänderter Inhalt wird unter einer neuen metadata.version veröffentlicht; aggrega lint --pre-publish beantwortet die nächste Frage — wie weit diese Version sich bewegen muss —, indem es die Änderung gegenüber der zuvor veröffentlichten Version klassifiziert.

--dry-run gibt den Digest aus, den ein Push schreiben würde, neben der Referenz, unter der er ihn schreiben würde:

aggrega push (dry-run): <reference>:<tag> (<digest>)

Es ist der Digest, den der Push selbst mit dem bereits Veröffentlichten vergleicht, auf dieselbe Weise allein aus dem Inhalt berechnet, und seine Ausgabe kontaktiert keine Registry. So kann der vorliegende Inhalt mit dem Digest abgeglichen werden, unter dem eine Version veröffentlicht wurde, bevor irgendetwas gepusht wird: Wo sie sich bei einer veröffentlichten Version unterscheiden, würde der Push abgelehnt. Mit --pin-sources ist es der Digest des Verzeichnisses, wie es ist, wie unter Pinnen vor dem Veröffentlichen beschrieben.

Eine von einem früheren Push unvollständig gelassene Veröffentlichung abschließen

Ein Push schreibt zuerst den Inhalt und hängt Signatur und Veröffentlichungsdatum danach an, sodass ein Push, der an einem dieser Anhänge scheitert — nach seinen Wiederholungen —, den Inhalt ohne ihn veröffentlicht lässt und mit einem Exit-Code ungleich null endet, der nennt, was er nicht anhängen konnte. Derselbe Push, erneut ausgeführt, schließt diese Veröffentlichung ab. Er findet den Inhalt bereits veröffentlicht, gibt die Zeile Already published: aus, lädt nichts hoch und hängt an, was der Version noch fehlt, jeweils in der Zeile, die eine erste Veröffentlichung dafür ausgibt:

  • Die Signatur, wo dieser Push signiert. Sie wird angehängt, wenn die Version keine Signatur trägt, die als die dieser Veröffentlichung gilt. Wo Ihre Konfiguration eine Vertrauensrichtlinie für den Host des Ziels festlegt — einen public_key oder trusted_identities, oder für hub.aggrega.ai die eingebaute Baseline —, gilt eine Signatur, wenn sie unter dieser Richtlinie verifiziert wird, sodass eine Signatur, die die Richtlinie nicht zulässt, nie als die eigene der Veröffentlichung angesehen wird. Wo die Richtlinie keines von beiden festlegt, kann keine Signatur dagegen verifiziert werden, sodass jede Signatur gilt, die die Version trägt, und der Push nur eine Version signiert, die keine trägt; eine Beurteilung anhand der Verifizierung würde dort bei jedem Lauf eine weitere Signatur anhängen.
  • Das Veröffentlichungsdatum, wo die Regel für Daten eines verlangt — gelesen aus der soeben angehängten Signatur oder aus der bereits anerkannten — und die Version überhaupt keinen Published-at-Referrer trägt. Ein Push, der nicht signiert, schuldet ein Datum wie eine unsignierte Veröffentlichung, unabhängig davon, welche Signaturen der Version danach angehängt wurden. Das angegebene Datum ist die eigene Uhr dieses Push: der Zeitpunkt, zu dem die Veröffentlichung abgeschlossen wurde, der später liegt als der Zeitpunkt, zu dem der Inhalt zuerst ankam, da nichts, was die Registry ausliefert, diesen Moment aufzeichnet.

Einer bereits vollständigen Veröffentlichung wird nichts angehängt, wie oft der Push auch wiederholt wird. Bevor er etwas anhängt, liest der Push, welche Signaturen und Daten die Version trägt, und erstellt jede Signatur, die er schuldet. Eine Frage, die er nicht beantworten kann — eine Auflistung oder Signatur, die er nicht lesen kann, oder eine Signatur, die er nicht beurteilen kann, weil der Vertrauensanker nicht beschafft werden kann —, und eine Signatur, die er nicht erstellen kann, beenden den Lauf jeweils mit einem Exit-Code ungleich null, ohne etwas anzuhängen, statt so gewertet zu werden, als trüge die Version keine.

Wenn die Registry einen Schreibvorgang fehlschlagen lässt

Ein Push schreibt schrittweise in die Registry: den Inhalt — bei einem Plugin die Entität und ihre .wasm —, dann das Manifest, das ihn benennt, dann den Versions-Tag, dann die Signatur und das Veröffentlichungsdatum daneben. Jeder schreibende Schritt wird wiederholt, wenn er auf eine Weise scheitert, bei der ein späterer Versuch gelingen kann: Die Registry antwortet mit einem Serverfehler (beliebiger 5xx-Status, außer einem 503 mit Retry-After) oder 408 Request Timeout, oder die Verbindung läuft in ein Timeout, wird zurückgesetzt oder bricht mitten in einer Antwort ab. Ein Schritt wird höchstens dreimal versucht, mit einer halben Sekunde Wartezeit vor dem zweiten Versuch und einer Sekunde vor dem dritten.

Auf eine Registry, die um Verlangsamung bittet, wird gewartet, und dabei wird keiner dieser Versuche verbraucht. Bei einem 429 Too Many Requests oder einem 503 mit Retry-After wartet jede Anfrage an diese Registry — ein Lesevorgang ebenso wie ein Schreibvorgang — so lange, wie die Registry verlangt hat, und wird dann erneut gesendet, wobei ein Schritt, dessen Inhalt abgewiesen wurde, als neuer Upload von vorn beginnt, ohne feste Anzahl von Versuchen, bis die Registry fünf Minuten lang nichts anderes als „langsamer“ geantwortet hat. Eine Registry, die um Verlangsamung bittet beschreibt die Wartezeit und die Abweisung, die sie beendet.

Jeder Versuch ist ein neuer Upload derselben Bytes, nie ein erneutes Senden der fehlgeschlagenen Anfrage. Eine Registry, die den Body eines Uploads bereits angenommen hat, kann dieselbe Anfrage ein zweites Mal ablehnen, und ein neuer Upload ist das, was sie akzeptiert. Inhalte, die die Registry bereits enthält, gelten als hochgeladen, und ein wiederholter Schritt schreibt, was der erste Versuch geschrieben hätte, sodass ein Versuch, der ankam, dessen Antwort aber verloren ging, nichts doppelt ablegt: Das Manifest behält seinen Digest, und die Version trägt eine Signatur und ein Veröffentlichungsdatum.

Jeder andere Fehler beendet den Schritt sofort: ein abgelehnter Berechtigungsnachweis (401, 403 oder kein gespeicherter Berechtigungsnachweis für die Registry), jede andere Antwort der Registry, eine überhaupt nicht erreichbare Registry oder ein Push, den Sie unterbrechen. Ein Schritt, der nach seinem letzten Versuch noch scheitert, lässt den Befehl scheitern, und der Fehler nennt den Schritt — den Inhalt, das Manifest, den Tag, die Signatur oder das Veröffentlichungsdatum. Was frühere Schritte veröffentlicht haben, bleibt veröffentlicht; Signieren und Das Veröffentlichungsdatum erläutern, was das für die Version bedeutet.

Bei diesen Fehlern werden nur Schreibvorgänge wiederholt. Das Lesen dessen, was die Registry unter der Version bereits enthält, bevor etwas hochgeladen wird, nicht, auch wenn es wie jede Anfrage so lange wartet, wie eine Registry, die um Verlangsamung bittet, es verlangt.

Signieren

aggrega push kann das Artefakt beim Veröffentlichen signieren und die Signatur als OCI-Referrer anhängen — ein Sigstore-Bundle (cosign-kompatibel) auf dem unveränderlichen Manifest-Digest des Artefakts. Die Signatur ist ein Geschwister-Manifest, sodass das Signieren die veröffentlichten Bytes nie erneut pusht oder verändert. Der Referrer benennt sein Bundle signature.json, sodass ein generischer OCI-Client, der den Referrer über seinen Digest abruft, das Bundle in diese Datei schreibt.

Signieren erfolgt sign-before-push: Der Manifest-Digest ist vor dem Veröffentlichen bekannt, sodass aggrega push den Signierer erstellt und den Digest signiert, bevor irgendwelche Bytes die Registry erreichen. Kann der Signierer nicht erstellt werden oder scheitert das Signieren, wird der Push abgelehnt, bevor irgendetwas hochgeladen wird — nichts wird veröffentlicht, sodass ein fehlgeschlagenes Signieren nie unsignierte Inhalte in der Registry hinterlässt. Bevor er ablehnt, wird ein vorübergehend fehlgeschlagener Signieraufruf — jeder Fehler, bei dem ein Registry-Schreibvorgang wiederholt wird, oder die schlüssellose Zertifizierungsstelle, die meldet, dass sie das Identitätstoken nicht verarbeiten konnte — erneut versucht, bis zu drei Versuche mit denselben Wartezeiten. Innerhalb eines schlüssellosen Signieraufrufs wird eine Anfrage, die die Zertifizierungsstelle, das Transparenzprotokoll oder die Zeitstempelstelle mit 429 Too Many Requests oder einem Serverfehler beantwortet, zunächst erneut an diesen Dienst gesendet, wie aggrega sign beschreibt.

Die Signatur wird angehängt, nachdem der Inhalt angekommen ist, sodass ein fehlgeschlagenes Anhängen den Inhalt tatsächlich ohne sie veröffentlicht lässt. Das Anhängen ist ein Schreibvorgang, der wie unter Wenn die Registry einen Schreibvorgang nicht ausführt beschrieben wiederholt wird. Scheitert es weiterhin, endet der Befehl mit einem Exit-Code ungleich null und nennt die Signatur, die er nicht anhängen konnte, und ein Konsument, dessen Registry Signaturen verlangt, lehnt die Version ab, bis eine Signatur angehängt ist. Derselbe Push, erneut ausgeführt, hängt sie an, wie unter Eine von einem früheren Push unvollständig gelassene Veröffentlichung abschließen beschrieben; aggrega sign hängt per Referenz eine an die veröffentlichte Version an.

Eine Veröffentlichung verlangt eine Signatur, wenn der eigene signing-Block der Ziel-Registry required: true setzt oder der signing-Block der obersten Ebene dies für jede Registry tut — jeweils beschränkt auf die Arten, die sein kinds aufführt, sofern es welche aufführt. Eine solche Veröffentlichung signiert standardmäßig, und --sign fordert das Signieren ausdrücklich an. Es gibt kein Flag, um unsignierte Inhalte zu pushen, wo eine Signatur verlangt wird — ein solcher Push hält immer an.

Zwei Signiermodi:

  • Keyless (Standard) — ein kurzlebiger Schlüssel, der durch ein kurzlebiges Fulcio-Zertifikat an eine OIDC-Identität gebunden und im Rekor-Transparenzlog aufgezeichnet wird. Fulcio und Rekor verwenden standardmäßig die öffentlichen Sigstore-Instanzen (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). Der vertrauenswürdige Zeitstempel beim schlüssellosen Signieren stammt aus der Aufnahme in das Transparenzlog von Rekor; eine separate RFC3161-Zeitstempelstelle ist optional — geben Sie --timestamp-url mit einem vollständigen Endpunkt an, um eine zu aktivieren. An einem interaktiven Terminal benötigt das schlüssellose Signieren keine Flags: Die CLI öffnet einen Browser, um ein kurzlebiges OIDC-Identitätstoken zu beziehen. Unter GitHub Actions benötigt es ebenfalls keine: Die CLI erzeugt das OIDC-Token des Workflows automatisch über den Umgebungs-Endpunkt des Runners. Für andere nicht interaktive / CI-Nutzung exportieren Sie AGGREGA_IDENTITY_TOKEN (oder SIGSTORE_ID_TOKEN) oder übergeben --identity-token; ohne bereitgestelltes Token, ohne Umgebungs-Endpunkt und ohne Terminal wird der Push abgelehnt. Siehe environment-variables.md für das Token-Modell in CI.
  • Keyed (--key) — ein offline gehaltener ECDSA-P-256-Schlüssel (cosign-kompatibles PEM), der Ausweg für Umgebungen ohne OIDC-Identitätsanbieter. Es wird weder ein Identitätsanbieter noch eine Zertifizierungsstelle noch ein Transparenzprotokoll kontaktiert.

Die URLs der schlüssellosen Dienste und der Pfad des Schlüssels für das Keyed-Signieren können auch in .aggrega-config.yaml unter einem signing:-Block (global und pro Registry) festgelegt werden; ein Flag überschreibt die Konfiguration, und die Konfiguration überschreibt den öffentlichen Standard. Das OIDC-Identitätstoken ist nie ein Konfigurationsfeld (es ist ein kurzlebiges Geheimnis), und der private Schlüssel steht nie inline in der Konfiguration — nur ein Pfad zu ihm.

Das Veröffentlichungsdatum

Der Erstellungszeitpunkt des Manifests ist fixiert, sodass ein Manifest-Digest nur davon abhängt, was veröffentlicht wird, und nie davon, wann. Das Datum, an dem eine Version veröffentlicht wurde, wird stattdessen neben ihr mitgeführt, und woher es stammt, hängt von der Signatur ab:

  • Eine schlüssellose Signatur trägt es bereits. Ihr Eintrag im Transparenzlog zeichnet auf, wann das Log die Signatur aufgenommen hat, und das signierte Versprechen des Logs bestätigt diesen Zeitpunkt. aggrega push schreibt nichts weiter.
  • Eine Keyed-Signatur oder keine Signatur trägt keinen Zeitpunkt. Nachdem die Entität und eine etwaige Signatur angekommen sind, hängt aggrega push daher einen kleinen Published-at-Referrer an das Manifest an — für einen generischen OCI-Client published-at.json benannt —, der einen RFC-3339-Zeitstempel in UTC auf die Sekunde genau enthält, gelesen von der eigenen Uhr des veröffentlichenden Rechners. Er ist nicht signiert: Er ist die Aussage des Herausgebers, und ein Leser zeichnet ihn als solche auf. Die Zeile Publication date attached: meldet ihn.

Wie eine Signatur ist der Published-at-Referrer ein Geschwister-Manifest, das auf das veröffentlichte zurückverweist, sodass er keinen Digest verschiebt und keinen Tag ändert, und die Prüfung beim Veröffentlichen über eine vorhandene Version bleibt davon unberührt. Ein wiederholter Push desselben Inhalts hängt ein Datum nur an eine Version an, die keines trägt, und gibt dabei seine eigene Uhr an — siehe Eine von einem früheren Push unvollständig gelassene Veröffentlichung abschließen. Das Datum wird einmal von der Uhr gelesen, bevor das Anhängen zum ersten Mal versucht wird, sodass ein wiederholtes Anhängen — siehe Wenn die Registry einen Schreibvorgang nicht ausführt — dasselbe Datum angibt. Ein Push, der seinen Inhalt veröffentlicht hat, aber das Datum nach diesen Versuchen nicht anhängen konnte, endet mit einem Exit-Code ungleich null und nennt, was nicht angehängt wurde. aggrega registry update zeichnet das Datum jeder Version zusammen damit auf, aus welcher der beiden Quellen es stammt.

Offline

Veröffentlichen ist ein Netzwerk-Roundtrip und hat keine Form, die keiner ist, daher lehnt aggrega push im Offline-Modus — dem Top-Level-Schlüssel offline in einer Konfigurationsdatei, AGGREGA_OFFLINE oder --offline — ab, bevor es Ihre Entität liest. Die Ablehnung nennt, welche dieser drei Quellen den Modus gesetzt hat, und genau das braucht ein Leser, wenn die eingecheckte Konfiguration eines Projekts ihn aktiviert hat und nicht etwas, das er eingegeben hat.

--dry-run ist die Ausnahme, und zwar wegen dessen, was es tut: Es berechnet das Bundle, gibt die Referenz aus, die es veröffentlichen würde, und den Digest, mit dem diese Veröffentlichung ankäme, und kontaktiert nie die Registry. Damit ist es die offline-sichere Form des Veröffentlichens und kein Konflikt mit dem Modus, und es funktioniert darin weiter — mit einer Einschränkung. Bei einem Recipe oder FeatureRecipe, dessen entfernte source: vollständig ausgeschrieben ist, wird diese Quelle abgerufen, um ihren Pin zu vergleichen, und im Offline-Modus wird dieser Abruf mit eigener Meldung abgelehnt, sodass ein Probelauf für eine solche Entität dort stoppt, statt ein Bundle zu melden, für das er nicht bürgen kann.

Um für einen Lauf aus einem Workspace zu veröffentlichen, dessen Konfiguration offline ist, übergeben Sie --offline=false.

Umgebungsvariablen

Die Signiereingaben und die Ziel-Registry können über die Umgebung angegeben werden und überschreiben .aggrega-config.yaml, während ein Flag weiterhin Vorrang hat:

  • AGGREGA_IDENTITY_TOKEN — das OIDC-Identitätstoken für schlüsselloses Signieren (das Umgebungs-Gegenstück zu --identity-token). SIGSTORE_ID_TOKEN wird als Interop-Alias des Sigstore-Ökosystems berücksichtigt, mit niedrigerem Rang als AGGREGA_IDENTITY_TOKEN und dem Umgebungs-Endpunkt von GitHub Actions. Das Token ist nie ein Konfigurationsfeld.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — die URLs der schlüssellosen Dienste.
  • AGGREGA_SIGNING_KEY_PATH — ein Pfadverweis auf ein PEM mit dem Schlüssel für Keyed-Signieren (nie Schlüsselmaterial).
  • AGGREGA_DEFAULT_REGISTRY — die Ziel-Registry, wenn --registry weggelassen wird.

Die Rangfolge ist Flag > Umgebung > Konfiguration > Standard. Siehe environment-variables.md für die vollständige Liste und das Vorrangmodell.

Authentifizierung

aggrega push liest Registry-Anmeldedaten so wie aggrega pull — aus der Docker-Anmeldedatenkonfiguration und den Credential-Helpern, die sie nennt. Führen Sie aggrega login <registry>, das kein anderes Tool benötigt, oder docker login <registry> aus, bevor Sie in eine private Registry pushen. Siehe aggrega-pull.md dazu, wo diese Konfiguration gelesen wird.

Siehe auch

  • ./aggrega-sign.md — signiert ein bereits veröffentlichtes Artefakt nachträglich (das Gegenstück zu --sign nach der Veröffentlichung).
  • ./aggrega-lint.md — die Veröffentlichungsprüfung (--pre-publish), die einem Push vorausgehen sollte.
  • ./aggrega-pull.md — die konsumierende Seite, die auflöst und pinnt, was push veröffentlicht.
  • ./aggrega-serve.md — der Daemon bietet dieselbe Veröffentlichung unter aggrega/publishEntity, sodass ein Editor sie ausführen kann, ohne die Sitzung zu verlassen; sie läuft nur, wenn eine Anfrage sie benennt, und antwortet mit der Referenz, dem veröffentlichten Digest — bei einem Probelauf dem Digest, den --dry-run ausgibt —, wie weit der Aufruf gekommen ist, und den Einträgen, vor denen dieser Befehl warnt, als windowsUnusableEntries.
  • ./aggrega-mcp.md — dieselbe Fähigkeit als Werkzeug publish-entity, das ein Assistent aufrufen kann und das mit diesen Einträgen als windows_unusable_entries antwortet. Lesen Sie, was diese Seite über das Zulassen sagt, bevor Sie es tun.
  • ../../architecture/13-catalog-and-registry.md — das Modell von Katalog, Registry und OCI-Medientypen im Detail.

Übersicht

aggrega push <entity-path> [flags]

Beschreibung

Publish a single catalog entity to an OCI registry, where other workspaces
resolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to
<registry>/<kind>/<metadata.name>:<metadata.version>, the repository path
lowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Plugin
its metadata.pluginType, as a segment between <kind> and <metadata.name>. The
tag is the entity's own metadata.version. Run "aggrega push --list-kinds" for
the kinds this binary publishes, one per line and nothing else, so a script can
read it directly. Release and Manifest are deployment-side inputs rather than
catalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: an
entity of any other kind is refused when another entity sits in its directory,
before anything is pinned or bundled, and the refusal names the entity in the way.
The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads it
before it is bundled, and one that read refuses is refused here for the same
reason: a document that fails its kind's schema, a path naming content outside
the entity's own directory, which would not travel with the entity, or a schema
a Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so a
metadata.version that is not a semantic version is refused. Its .wasm must then
agree with the entity on what the plugin offers and on its version, and a .wasm
whose version says it was built from a working tree with uncommitted changes —
the -dirty mark a build adds — is refused. A version disagreement and a build
from uncommitted changes are both cleared by building the plugin from a clean
checkout of the commit its release tag names, never by copying the version it
reports into the entity. A development version such as 1.0.0-3-g1a2b3c4, built
from a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself names
beside it — a Recipe's or FeatureRecipe's local source, each file an $import:
names, the entity.lock beside it, and each schema file a Component or Feature
imports — and nothing else in its directory. An entity that names nothing
publishes as its document, unchanged; one that names a file publishes as a
gzipped archive of the document and those files. A directory it names travels
with every file under it that the ignore rules recorded in its entity.lock keep:
the rules the plugin serving its capability declared, and the author's own
.aggregaignore beside it, composed when the entity was pinned. A symbolic link
among those files is refused rather than followed. A local source written as a
template names no one directory until a Release fills it in, so an entity with
one carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windows
cannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,
NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or a
part ending in a full stop or a space. On Windows, aggrega refuses to unpack
such a file, so a Windows workspace cannot use the version. The warning is
written to standard error on every platform, one line per file, the entity
document's own file name judged with the rest, and it refuses nothing: the push,
or its dry run, goes ahead or stops exactly as it would without it. An entity
that names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the execute
bit included — in the checkout it is published from. The OCI manifest names the
digest of the published bytes, so "aggrega pull" refuses a download that does
not match it. The lockfile a pull writes records the entity by the digest of its
content — each file's path and its bytes — which is the digest a pull in the
author's own workspace records for the same entity in its catalog directory, so
a build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is made
over the manifest digest before any bytes reach the registry, so a failed
signing refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what is
published and never on when. Push states when it published beside the manifest
instead, as a small published-at attachment carrying this machine's clock, in
UTC to the second — unless the signature it attached already carries a time a
transparency log attests, as a keyless signature does. So a keyed or unsigned
publication writes one, and a keyless one does not. The attachment moves no
digest and changes no tag. "aggrega registry update" records the date, with
which of the two it came from.
Push refuses to replace content already published at the same version:
publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lock
beside it, and pinning them is a step you run before publishing: aggrega pin.
A push that does not run that step refuses an entity whose entity.lock is
missing a pin, or holds one an input no longer matches, and names the step.
Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, to
have push run that same step first, so the lock it writes is part of what is
published; --pin-sources=false skips it for one run.

Flags

FlagStandardBeschreibung
--dry-runfalseBerechnet das Bundle und gibt die vorgeschlagene : mit dem Digest aus, mit dem eine Veröffentlichung ankäme, ohne die Registry zu kontaktieren. Eine Entität, die die Veröffentlichung wegen eines fehlenden Pins ablehnen würde, wird auch hier abgelehnt
--entity—Pfad zur zu veröffentlichenden Entitäts-YAML (alternativ als Positionsargument übergeben)
--fulcio-url—URL der Fulcio-Zertifizierungsstelle für schlüssellose Signierung. Wenn weggelassen, wird die öffentliche Fulcio-Instanz verwendet.
--identity-token—OIDC-Identitätstoken für schlüssellose Signierung. Optional an einem interaktiven Terminal (ein Browser-Ablauf beschafft eines) und in GitHub Actions (das OIDC-Token des Workflows wird automatisch ausgestellt); erforderlich für andere nicht interaktive Verwendung/CI, wo es stattdessen als AGGREGA_IDENTITY_TOKEN oder SIGSTORE_ID_TOKEN exportiert werden kann.
--key—Pfad zu einer vorliegenden privaten ECDSA-P-256-Schlüssel-PEM für die Offline-Signierung mit Schlüssel. Wenn weggelassen, wird schlüssellose Signierung verwendet.
--list-kindsfalseListet jede Entitätsart auf, die veröffentlicht werden kann, und beendet sich dann, ohne etwas zu veröffentlichen. Die Ausgabe ist maschinenlesbar und ihre Form ist stabil: eine Art pro Zeile, sortiert, ohne sonst etwas.
--pin-sourcesfalseFührt den Pin-Schritt des Entitätsautors für die Entität aus, bevor sie gebündelt wird, sodass die entity.lock, die der Schritt neben sie schreibt, Teil des Veröffentlichten ist, statt eine Entität abzulehnen, deren Lock ihre Pins nicht aufzeichnet. Derselbe Schritt wie aggrega pin, der dieselben Bytes schreibt. Er schreibt neben die Entität und läuft daher nur dort, wo die Entität einen beschreibbaren Ort hat: ein Dokument in einem Verzeichnis, aus dem sie gelesen wurde — den ein Push immer hat, da er das von Ihnen benannte Entitätsdokument veröffentlicht. Überschreibt pin_sources_at_push des Workspace in beide Richtungen: —pin-sources pinnt für diesen Lauf und —pin-sources=false nicht, unabhängig von der Einstellung
--plugin—Pfad zum lokalen .wasm-Artefakt für eine Plugin-Entität. Erforderlich beim Veröffentlichen eines Plugin: Die Veröffentlichung pusht das .wasm-Artefakt, berechnet seinen Inhalts-Digest und pusht die Entität.
--registry—Host der Ziel-Registry (überschreibt die default_registry des Workspace)
--rekor-url—URL des Rekor-Transparenzlogs für schlüssellose Signierung. Wenn weggelassen, wird die öffentliche Rekor-Instanz verwendet.
--signfalseSigniert das veröffentlichte Artefakt und hängt die Signatur als OCI-Referrer an. Wenn weggelassen, folgt das Signieren der Richtlinie der Ziel-Registry.
--timestamp-url—Optionale URL einer RFC3161-Zeitstempelstelle für schlüssellose Signierung.