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

aggrega deprecate

Einen signierten Veraltungsmarker an ein bereits veröffentlichtes Artefakt anhängen

Übersicht

aggrega deprecate <reference> [flags]

Beschreibung

Deprecate amends an already-published artifact by attaching a deprecation marker to it as an OCI referrer, then signing that marker. It does not re-push, re-tag, or otherwise mutate the published bytes — the artifact is immutable; the marker is a sibling manifest pointing back at it, so a marker can be attached retroactively. The marker records a severity (warning, error, or retracted), a reason, an optional replacement reference, and the timestamp it was issued. Run it three ways: pass the content as flags; omit the content flags at an interactive terminal to be prompted for severity, reason, and replacement; or pass --from <file> to attach one marker per entry from a batch file, whose entries carry their own content, so a content flag passed beside --from is refused rather than ignored. The marker itself is signed the same way artifacts are: its manifest digest is signed and the signature is attached as a referrer of the marker, so the marker is verifiable the same way artifact signatures are. With --key the signature is produced offline from a held ECDSA P-256 key; without --key the keyless flow is used, which requires a live identity provider, Fulcio, and Rekor. Every marker of one --from batch is signed with one credential: where the configuration names a held key (signing.key_path) for one entry's registry and none for another's, or two different keys, no marker is attached and the command says to run one batch per credential.

Flags

FlagStandardBeschreibung
--from—Batch-Datei (YAML oder JSON als Teilmenge), deren Liste auf oberster Ebene pro Eintrag eine Markierung anhängt. Jeder Eintrag enthält reference, severity und reason sowie optional replacement und message. Schließt sich mit einer positionalen Referenz sowie mit —severity, —reason, —replacement und —message gegenseitig aus.
--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.
--message—Optionale Meldung, die für Audits und für die aufgezeichnete Build-Zeit-Diagnose aufbewahrt wird; standardmäßig —reason, wenn nicht gesetzt. Wird neben —from abgelehnt, dessen Einträge ihre eigene mitbringen.
--reason—Menschenlesbarer Grund für die Deprecation — warum es veraltet ist und was stattdessen zu tun ist. Bei einer positionalen Referenz erforderlich, sofern nicht eine interaktive Abfrage ihn liefert; wird neben —from abgelehnt, dessen Einträge ihren eigenen mitbringen.
--rekor-url—URL des Rekor-Transparenzlogs für schlüssellose Signierung. Wenn weggelassen, wird die öffentliche Rekor-Instanz verwendet.
--replacement—Optionale Artefaktreferenz, die die veraltete ersetzt. Wird neben —from abgelehnt, dessen Einträge ihre eigene mitbringen.
--severity—Schweregrad der Deprecation: einer von warning, error, retracted. Bei einer positionalen Referenz erforderlich, sofern nicht eine interaktive Abfrage ihn liefert; wird neben —from abgelehnt, dessen Einträge ihren eigenen mitbringen.
--timestamp-url—Optionale URL einer RFC3161-Zeitstempelstelle für schlüssellose Signierung.

Woher die Signatur-Endpunkte stammen

Die Fulcio- und Rekor-URLs für schlüsselloses Signieren und der Schlüsselpfad für das Signieren mit Schlüssel können auch aus dem signing:-Block der .aggrega-config.yaml stammen (global und pro Registry, wobei ein für die Registry des Artefakts gesetzter Wert Feld für Feld Vorrang vor dem globalen hat); ein Flag überschreibt die Konfiguration, und die Konfiguration überschreibt den Public-Good-Standard. Die in der Flag-Tabelle genannten Public-Good-Instanzen werden also nur verwendet, wo weder ein Flag noch Ihre Workspace-Konfiguration einen Endpunkt nennt. Die Markierung wird genau so signiert, wie aggrega sign ein Artefakt signiert.

Wenn die Registry einen Schreibvorgang fehlschlagen lässt

Das Markieren eines Artefakts als veraltet schreibt zweimal in die Registry: die Markierung, angehängt als Referrer des Artefakts, und dann die Signatur der Markierung, angehängt als Referrer der Markierung. Jeder Schreibvorgang wird wiederholt, wenn die Registry oder das Netzwerk ihn auf eine Weise fehlschlagen lässt, bei der ein späterer Versuch erfolgreich sein kann, etwa bei einem Serverfehler, einer Zeitüberschreitung oder einer zurückgesetzten Verbindung; aggrega push listet diese Fehler auf. Ein Schreibvorgang wird höchstens dreimal versucht, im Abstand von einer halben und dann einer Sekunde, und jeder Versuch ist ein neuer Upload derselben Bytes statt eines erneuten Sendens der fehlgeschlagenen Anfrage. Der Zeitstempel der Markierung wird einmal vor dem ersten Versuch gesetzt, sodass ein wiederholter Schreibvorgang eine Markierung und eine Signatur hinterlässt, nicht zwei.

Das Signieren der Markierung zwischen den beiden Schreibvorgängen wird nicht als Ganzes wiederholt; innerhalb einer schlüssellosen Signierung wird eine Anfrage, die die Zertifizierungsstelle, das Transparenzlog oder die Zeitstempelstelle mit 429 Too Many Requests oder einem Serverfehler beantwortet, erneut an diesen Dienst gesendet, wie aggrega sign beschreibt. Ein Schreibvorgang, der nach seinem letzten Versuch weiterhin fehlschlägt, oder eine fehlschlagende Signierung beendet den Befehl und nennt den Schritt; eine bis dahin bereits angehängte Markierung bleibt ohne ihre Signatur angehängt. Mit --from bleiben die Einträge, die vor dem fehlgeschlagenen angehängt wurden, angehängt.

Eine Batch-Datei enthält den Inhalt jeder Markierung

Mit --from stammen Schweregrad, Grund, Ersatz und Meldung jeder Markierung aus ihrem eigenen Eintrag in der Batch-Datei. Ein neben --from übergebenes --severity, --reason, --replacement oder --message wird daher abgelehnt statt ignoriert: Der Befehl nennt jedes übergebene und bricht ab, bevor die Batch-Datei gelesen wird, sodass keine Markierung angehängt wird. Tragen Sie den Inhalt in die Einträge der Datei ein, oder markieren Sie eine einzelne Referenz mit ihren Inhalts-Flags als veraltet.

Ein Batch wird mit einer einzigen Anmeldeinformation signiert

Mit --from wird jede Markierung in der Batch-Datei mit derselben Anmeldeinformation signiert: einem einzigen vorliegenden Schlüssel oder einer einzigen schlüssellosen Identität, die einmal für die gesamte Datei abgefragt wird. Welche ein Eintrag benötigt, entscheidet die Konfiguration für die Registry seiner Referenz — ein signing.key_path, der für diese Registry gilt, wählt den Schlüssel, den er nennt, und wo keiner gilt, wird die Markierung schlüssellos signiert. Wenn die Einträge unterschiedliche Anmeldeinformationen benötigen würden — die Konfiguration nennt einen Schlüssel für eine Registry und keinen für eine andere, oder zwei verschiedene Schlüssel —, wird keine Markierung angehängt, und der Befehl nennt die Registries auf jeder Seite. Er tut dies, bevor eine Identität abgefragt und bevor eine Registry gelesen wird.

Teilen Sie die Datei in einen Batch pro Anmeldeinformation auf oder übergeben Sie einen Schlüssel mit --key, der für jeden Eintrag gilt, unabhängig davon, was die Konfiguration für die einzelnen Registries sagt. Die Meldung ist beschrieben unter References signed together need different signing credentials (Gemeinsam signierte Referenzen benötigen unterschiedliche Signatur-Anmeldeinformationen).

Der Signierer jedes Eintrags wird ebenfalls vorbereitet, bevor die erste Markierung angehängt wird, sodass ein Schlüssel, der nicht gelesen werden kann, oder ein bereitgestelltes Identitätstoken ohne verwendbares Subject den Batch beendet, ohne dass etwas angehängt wurde.

Was jeder Schweregrad bewirkt

Die drei Schweregrade bilden eine geordnete Menge — warning, dann error, dann retracted — und teilen sich in zwei Stufen, die sich darin unterscheiden, wann sie wirken.

warning und error sind beratende Stufen. Eine Markierung mit einem dieser Schweregrade ändert nie, zu welcher Version eine Referenz aufgelöst wird. Sie wird aufgezeichnet, wenn Sie aggrega pull ausführen, und jede Oberfläche, die die Lockfile liest, meldet sie.

Jede dieser Oberflächen meldet jede veraltete Referenz, die die Lockfile pinnt, unabhängig vom Schweregrad, und nennt die Referenz, ihren Schweregrad, ihre Meldung und wann der Eintrag beobachtet wurde:

OberflächeWas sie mit einer aufgezeichneten Markierung tut
aggrega buildMeldet sie und hält an, wenn Sie bei diesem Schweregrad einen Abbruch konfiguriert haben.
aggrega validate --releaseMeldet sie. Das Urteil bleibt unverändert.
aggrega lint --releaseMeldet sie. Das Urteil bleibt unverändert.
aggrega serveVeröffentlicht ihn in Ihrem Editor als Warnung, solange das Aggregate geöffnet ist. Ein Marker nennt eine Referenz oder ein Plugin statt eines Dokuments in Ihrem Workspace, daher bleibt er am Aggregate; nur die eigenen Mapping-Fehler eines Manifest werden am Manifest angezeigt.
Das KI-native Tool buildMeldet sie und verweigert, wenn Sie bei diesem Schweregrad einen Abbruch konfiguriert haben.
Die KI-nativen Tools describe und validateMelden sie zusammen mit ihrer eigenen Ausgabe.

Ob eine Markierung einen Build auch anhält, ist eine separate Einstellung: build.halt_on_deprecated_severity ist standardmäßig nicht gesetzt, sodass nichts anhält, und wird sie auf einen Schweregrad gesetzt, hält der Build bei diesem Schweregrad und darüber an. Sie steuert den Build — aggrega build und das KI-native Build-Tool, das derselbe Vorgang ist — und nichts anderes: Die meldenden Oberflächen nennen die Markierung und fahren in jedem Fall fort. Das Anheben des Schwellenwerts verringert nie, was Ihnen mitgeteilt wird, auf keiner Oberfläche — Sie erhalten weiterhin den Hinweis für alles darunter und für alles, was der Abbruch nicht abdeckt.

Einige Plugins werden an anderer Stelle aufgezeichnet, und ihre Markierungen stammen von dort. Ein plugins.linter-Attachment und ein plugins.governance-Attachment in einer ir-verdict- oder render-verdict-Rolle prägen nichts von der gerenderten Ausgabe, daher werden sie in plugins-trust.yaml neben der Lockfile gepinnt statt in der Lockfile selbst. Jeder Eintrag dort enthält die Markierung, die für das genannte Plugin gefunden wurde, neben seiner Identität, und aggrega pull zeichnet eine auf dieselbe Weise auf, wie es eine Markierung in einer Lockfile-Zeile aufzeichnet.

aggrega build, aggrega lint --release und aggrega validate --release lesen beide Aufzeichnungen, sodass ein veraltetes Plugin dort genauso genannt wird wie eine veraltete Referenz, und build.halt_on_deprecated_severity steuert beide gleichermaßen. Zwei Unterschiede sind wissenswert. Der Hinweis für ein solches Plugin sagt nicht, wann der Eintrag beobachtet wurde — diese Datei enthält überhaupt keine Zeitstempel, wodurch sie sich byteweise identisch reproduzieren lässt —, daher nennt er stattdessen, woher die Information stammt, und den Befehl, der sie aktualisiert. Und ein Eintrag dort wird nie durch einen gewöhnlichen Pull neu geschrieben: Eine neu veröffentlichte Markierung wird dem Eintrag hinzugefügt, den das Plugin bereits hat, während die Identität, an die es gebunden ist, unverändert bleibt, bis Sie mit aggrega pull --upgrade eine Änderung anfordern.

retracted ist die Rückzugsstufe, und sie wirkt auch früher. Eine als zurückgezogen aufgezeichnete Version wird aus der Betrachtung entfernt, wenn aggrega pull eine Version für eine Referenz auswählt, die keine genannt hat. Wenn eine andere veröffentlichte Version die Referenz erfüllt, wird diese Version genommen, und der Pull sagt das und nennt die übersprungene Version, den dafür aufgezeichneten Grund und die stattdessen genommene Version. Wenn keine veröffentlichte Version mehr übrig ist, die die Referenz erfüllt, hält der Pull an und sagt, dass jeder Kandidat zurückgezogen wurde — er meldet die Entität nicht als fehlend und weicht nie stillschweigend aus.

Die explizite Angabe einer Version setzt den Rückzug außer Kraft

Eine Referenz, die eine exakte Version nennt, wird immer zu dieser Version aufgelöst, unabhängig davon, ob sie zurückgezogen wurde. Die Angabe der Version ist die Außerkraftsetzung, daher gibt es keine separate Einstellung, um den Ausschluss abzuschalten — und eine gepinnte Version aus einem früheren aggrega pull wird aus genau demselben Grund weiterhin aufgelöst.

Der Pull sagt es deutlich, wenn die von Ihnen genannte Version zurückgezogen wurde, sodass der Build, der sich bereits darauf festgelegt hat, weiter funktioniert, während Sie dennoch sehen können, warum Sie vielleicht wechseln möchten.

Rückzugsaufzeichnungen sind ein Schnappschuss, keine Live-Antwort

Ein veröffentlichtes Artefakt ist unveränderlich, ein Rückzug jedoch nicht: Eine Version kann zurückgezogen werden, nachdem Sie zuletzt nachgesehen haben. Der Ausschluss liest, was Ihr Workspace beim letzten Aufbau seines lokalen Registry-Index aufgezeichnet hat, sodass er Sie davor schützt, eine Version auszuwählen, von der bekannt ist, dass sie zurückgezogen wurde. Er kann Ihnen nicht sagen, dass eine Version gerade jetzt nicht zurückgezogen ist.

Jede Meldung einer früher aufgezeichneten Markierung gibt an, wann dieser Eintrag beobachtet wurde, sodass ein veralteter Eintrag von einem frischen unterscheidbar ist, und jede nennt den Befehl, der ihn aktualisiert. Es werden zwei Aufzeichnungen geführt, die getrennt aktualisiert werden: Der Versionsausschluss und aggrega inspect lesen Ihren lokalen Registry-Index, den aggrega registry update aktualisiert, während aggrega build die in der Lockfile aufgezeichnete Markierung liest, die aggrega pull aktualisiert. Was aggrega pull ausgibt, während es sucht, trägt keinen solchen Zeitpunkt — es meldet, was es gerade eben gefunden hat.

Aus demselben Grund ist das Fehlen eines Rückzugs kein Beleg dafür, dass keiner existiert — nur dafür, dass bei Ihrer letzten Aktualisierung keiner aufgezeichnet war.

Wo Sie informiert werden

Welcher Befehl Sie über eine Rücknahme informiert, ergibt sich daraus, welchen Datensatz er liest. Die Tabelle weiter oben behandelt den in Ihrem Lockfile erfassten Marker – was dieses Release festgelegt hat. Diese hier behandelt den lokalen Registry-Index – was eine Registry veröffentlicht hat –, also den Datensatz, den der Versionsausschluss liest.

BefehlWas er Ihnen über eine erfasste Rücknahme mitteilt
aggrega registry updateNennt jeden Marker, auf den er beim Durchlaufen der Registry trifft: das Repository, die Version, für die er erfasst wurde, den Schweregrad und ob der Marker erfasst wurde. Anschließend meldet jede Registry, wie viele Marker ihr Index nun enthält.
aggrega searchMeldet die Version, die eine Auflösung nehmen würde, statt einer zurückgezogenen, und nennt die zurückgezogenen Versionen in einer Spalte NOTES. --include-retracted meldet stattdessen die höchste veröffentlichte Version.
aggrega inspectGibt den erfassten Schweregrad unterhalb der Entität aus, mit der Version, für die er erfasst wurde, dem Grund, dem Ersatz, sofern einer genannt ist, und dem Ausstellungsdatum – für jede Art, die er über den Namen auflöst.
aggrega pullNennt jede übersprungene Version, den dafür erfassten Grund und die stattdessen genommene Version. Eine Version, die Sie explizit angegeben haben, wird trotzdem aufgelöst, und die Rücknahme wird angekündigt, statt angewendet zu werden.
aggrega plugin addDasselbe: Eine Version, die er wählt, wird auf beiden Wegen geprüft, über die er eine auflöst, und eine Version, die Sie als <name>:<version> nennen, wird weiterhin aufgelöst, wobei die Rücknahme angekündigt wird. Wo die Marker nicht gelesen werden konnten, sagt er dies und gibt an, dass die veröffentlichten Versionen nicht geprüft wurden.
aggrega buildNichts aus diesem Datensatz. Er liest nur Ihr Lockfile und nie den Index, daher meldet er den Marker, der für die von Ihnen festgelegte Version erfasst ist.
aggrega serveNichts aus diesem Datensatz. Seine eigene Auflösung zieht die Rücknahme-Datensätze nicht heran, sodass dort weiterhin eine zurückgezogene Version ausgewählt werden kann; den Marker des Lockfiles übermittelt er an Ihren Editor.

Lesen Sie die letzten beiden Zeilen zusammen mit den übrigen: Ein Befehl informiert Sie nur dort über eine Rücknahme, wo er etwas tut, das die Rücknahme betrifft – eine Version auswählen oder Ihnen zeigen, was ein Herausgeber mitgeteilt hat. Schweigen eines Befehls, der keines von beidem tut, ist kein Beleg dafür, dass nichts erfasst ist.

Ein Hinweis nennt den Schweregrad, den der Herausgeber erfasst hat. Ein zurückgezogenes Artefakt wird als retracted gemeldet; die beiden empfehlenden Schweregrade werden als veraltet gemeldet, mit Angabe, welcher der beiden. So entspricht das, was Sie zurücklesen, dem Wert, der verfasst wurde, und dem Wert, mit dem Sie einen Abbruchschwellenwert konfigurieren würden.

Zwei Arten von Hinweisen werden getrennt gehalten, weil sie unterschiedliche Ereignisse melden. Eine Zeile deprecation: teilt Ihnen etwas über ein Artefakt mit. Eine Zeile retraction: teilt Ihnen mit, was Sie nicht erhalten haben – eine übersprungene Version oder eine Prüfung, die nicht durchgeführt werden konnte. Wo ein Befehl beide zum selben Artefakt ausgibt, sind es zwei Fakten und nicht eine zweimal gemachte Aussage.

Welche Auflösungen der Ausschluss abdeckt

Der Ausschluss greift überall dort, wo ein Befehl für Sie eine Version auswählt. Das ist die Regel, und sie entscheidet, ob eine bestimmte Auflösung abgedeckt ist.

aggrega pull wendet ihn überall dort an, wo es eine Version für eine Referenz auswählt, die keine angegeben hat – unabhängig davon, was die Referenz benennt: eine Katalogentität, eine Bibliothek, ein veröffentlichtes Aggregate. Eine einzige Regel gilt für alle, daher hängt die Version, zu der eine Referenz aufgelöst wird, nicht davon ab, welche Art von Referenz sie angefordert hat.

aggrega plugin add wendet ihn auf jedem Weg an, über den es eine nicht festgelegte Plugin-Referenz auflöst: gegen die veröffentlichten Versionen, die Ihr lokaler Registry-Index bereits enthält, und gegen die Live-Versionsliste, auf die es zurückgreift, wenn dieser Index das Repository nicht enthält. Eine zurückgenommene Version wird übersprungen und die Ersetzung angekündigt, auf welchem Weg auch immer sie aufgelöst wurde.

Der editorseitige Daemon ist die Ausnahme. Er löst Referenzen bei Bedarf auf, während er einen Editor bedient, und diese Auflösung wählt Versionen aus, ohne die Rücknahme-Datensätze heranzuziehen, sodass dort weiterhin eine als zurückgezogen erfasste Version ausgewählt werden kann.

Wo nichts ausgewählt wird, hat der Ausschluss nichts, worauf er wirken könnte: Eine Referenz, die eine exakte Version nennt, wird zu dieser Version aufgelöst, und die Rücknahme wird angekündigt, statt angewendet zu werden. Ebenso ändert nichts davon, was Ihnen zur Build-Zeit mitgeteilt wird – aggrega build meldet jeden Marker, den das Lockfile erfasst, unabhängig davon, auf welchem Weg die Version festgelegt wurde.

Siehe auch

  • ./aggrega-sign.md – ein Marker wird über seinen eigenen Digest signiert, daher sind die Signiermodi und die jeweils benötigten Anmeldedaten die dort beschriebenen.
  • ./aggrega-serve.md – der Daemon bringt denselben Marker unter aggrega/deprecateArtifact an. Der Inhalt, der in einem Terminal abgefragt wird, ist dort in einer Anfrage erforderlich, weil nichts auf dieser Oberfläche danach fragen kann.
  • ./aggrega-mcp.md – dieselbe Funktion als Tool deprecate-artifact, das ein Assistent aufrufen kann. Lesen Sie, was diese Seite über das Zulassen sagt, bevor Sie es tun: Eine Rücknahme ändert, was jeder Konsument dieser Registry auflöst.