Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega deprecate

Dołącza podpisany znacznik wycofania do już opublikowanego artefaktu

Składnia

aggrega deprecate <reference> [flags]

Opis

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.

Flagi

FlagaDomyślnieOpis
--from—Plik wsadowy (YAML lub JSON jako jego podzbiór), którego lista najwyższego poziomu dołącza jeden znacznik na każdy wpis. Każdy wpis zawiera reference, severity i reason oraz opcjonalnie replacement i message. Wyklucza się z referencją podaną jako argument pozycyjny oraz z —severity, —reason, —replacement i —message.
--fulcio-url—Adres URL urzędu certyfikacji Fulcio do podpisywania bezkluczowego. Jeśli zostanie pominięty, używana jest publiczna instancja Fulcio.
--identity-token—Token tożsamości OIDC do podpisywania bezkluczowego. Opcjonalny w interaktywnym terminalu (token uzyskuje się w przeglądarce) oraz w GitHub Actions (token OIDC przepływu pracy jest generowany automatycznie); wymagany w pozostałych zastosowaniach nieinteraktywnych/CI, gdzie można go zamiast tego wyeksportować jako AGGREGA_IDENTITY_TOKEN lub SIGSTORE_ID_TOKEN.
--key—Ścieżka do posiadanego klucza prywatnego ECDSA P-256 w formacie PEM do podpisywania kluczem w trybie offline. Jeśli zostanie pominięta, używane jest podpisywanie bezkluczowe.
--message—Opcjonalny komunikat, zachowywany na potrzeby audytu i zapisywanej diagnostyki czasu budowania; jeśli nie jest ustawiony, przyjmuje wartość —reason. Odrzucany obok —from, którego wpisy zawierają własny.
--reason—Czytelny dla człowieka powód wycofania — dlaczego artefakt jest wycofany i czego używać zamiast niego. Wymagany przy referencji podanej jako argument pozycyjny, chyba że dostarcza go interaktywny monit; odrzucany obok —from, którego wpisy zawierają własny.
--rekor-url—Adres URL dziennika przejrzystości Rekor do podpisywania bezkluczowego. Jeśli zostanie pominięty, używana jest publiczna instancja Rekor.
--replacement—Opcjonalna referencja artefaktu, który zastępuje artefakt wycofany. Odrzucana obok —from, którego wpisy zawierają własną.
--severity—Poziom wycofania: jeden z warning, error, retracted. Wymagany przy referencji podanej jako argument pozycyjny, chyba że dostarcza go interaktywny monit; odrzucany obok —from, którego wpisy zawierają własny.
--timestamp-url—Opcjonalny adres URL urzędu znaczników czasu RFC3161 do podpisywania bezkluczowego.

Skąd pochodzą punkty końcowe podpisywania

Adresy URL Fulcio i Rekor dla podpisywania bezkluczowego oraz ścieżka klucza dla podpisywania kluczem mogą również pochodzić z bloku signing: w .aggrega-config.yaml (globalnego i dla poszczególnych rejestrów, przy czym wartość ustawiona dla rejestru artefaktu ma pierwszeństwo przed globalną, pole po polu); flaga nadpisuje konfigurację, a konfiguracja nadpisuje publiczną wartość domyślną. Instancje publiczne wymienione w tabeli flag są więc używane tylko wtedy, gdy ani flaga, ani konfiguracja obszaru roboczego nie wskazuje punktu końcowego. Znacznik jest podpisywany dokładnie tak, jak aggrega sign podpisuje artefakt.

Gdy rejestr odrzuci zapis

Wycofanie artefaktu zapisuje do rejestru dwa razy: znacznik, dołączany jako referrer artefaktu, a następnie podpis znacznika, dołączany jako referrer znacznika. Każdy zapis jest ponawiany, gdy rejestr lub sieć zawiedzie w sposób, w jaki późniejsza próba może się powieść, np. błąd serwera, przekroczenie czasu lub zerwane połączenie; aggrega push wymienia te błędy. Zapis jest próbowany najwyżej trzy razy, w odstępach pół sekundy, a następnie sekundy, a każda próba jest nowym przesłaniem tych samych bajtów, a nie ponownym wysłaniem żądania, które zawiodło. Znacznik czasu znacznika jest ustalany raz, przed pierwszą próbą, więc ponowiony zapis pozostawia jeden znacznik i jeden podpis, a nie dwa.

Podpisywanie znacznika, między dwoma zapisami, nie jest ponawiane jako całość; w ramach podpisywania bezkluczowego żądanie, na które urząd certyfikacji, dziennik przejrzystości lub urząd znaczników czasu odpowie 429 Too Many Requests lub błędem serwera, jest wysyłane do tej usługi ponownie, jak opisuje aggrega sign. Zapis, który nadal zawodzi po ostatniej próbie, lub nieudane podpisywanie zatrzymuje polecenie i wskazuje krok; znacznik dołączony do tego czasu pozostaje dołączony bez podpisu. Z --from wpisy dołączone przed tym, który zawiódł, pozostają dołączone.

Plik wsadowy zawiera treść każdego znacznika

Z --from poziom, powód, zamiennik i komunikat każdego znacznika pochodzą z jego własnego wpisu w pliku wsadowym. Dlatego --severity, --reason, --replacement lub --message przekazane obok --from są odrzucane, a nie ignorowane: polecenie wymienia każdą przekazaną flagę i zatrzymuje się przed odczytaniem pliku wsadowego, więc żaden znacznik nie zostaje dołączony. Treść należy umieścić we wpisach pliku albo wycofać jedną referencję za pomocą jej flag treści.

Partia jest podpisywana jednym poświadczeniem

Z --from każdy znacznik w pliku partii jest podpisywany tym samym poświadczeniem: jednym posiadanym kluczem albo jedną tożsamością bezkluczową, o którą pytanie pada raz dla całego pliku. O tym, którego poświadczenia wymaga dany wpis, decyduje konfiguracja dla rejestru jego referencji — signing.key_path mające zastosowanie do tego rejestru wybiera wskazany w nim klucz, a gdy żadne nie ma zastosowania, znacznik jest podpisywany bezkluczowo. Gdy wpisy wymagałyby różnych poświadczeń — konfiguracja wskazuje klucz dla jednego rejestru, a dla innego żadnego, albo dwa różne klucze — żaden znacznik nie zostaje dołączony, a polecenie podaje rejestry po każdej ze stron. Dzieje się to, zanim nastąpi pytanie o jakąkolwiek tożsamość i zanim zostanie odczytany jakikolwiek rejestr.

Należy podzielić plik na osobne partie dla każdego poświadczenia albo przekazać jeden klucz przez --key, który ma zastosowanie do każdego wpisu niezależnie od tego, co konfiguracja mówi dla poszczególnych rejestrów. Komunikat opisano w sekcji References signed together need different signing credentials (Referencje podpisywane razem wymagają różnych poświadczeń podpisu).

Podpisujący dla każdego wpisu jest również przygotowywany przed dołączeniem pierwszego znacznika, więc klucz, którego nie można odczytać, lub dostarczony token tożsamości bez użytecznego podmiotu zatrzymuje partię, zanim cokolwiek zostanie dołączone.

Działanie poszczególnych poziomów ważności

Trzy poziomy ważności tworzą uporządkowany zbiór — warning, potem error, potem retracted — i dzielą się na dwie warstwy, które różnią się tym, kiedy działają.

warning i error to warstwy doradcze. Znacznik na żadnym z tych poziomów nigdy nie zmienia wersji, na którą rozwiązuje się odwołanie. Jest zapisywany przy uruchomieniu aggrega pull, a każde miejsce, które odczytuje plik blokady, go zgłasza.

Każde z tych miejsc zgłasza każde przestarzałe odwołanie przypięte w pliku blokady, niezależnie od poziomu ważności, podając odwołanie, jego poziom ważności, komunikat oraz czas zaobserwowania rekordu:

MiejsceCo robi z zapisanym znacznikiem
aggrega buildZgłasza go i zatrzymuje się, jeśli skonfigurowano zatrzymanie na tym poziomie ważności.
aggrega validate --releaseZgłasza go. Werdykt pozostaje bez zmian.
aggrega lint --releaseZgłasza go. Werdykt pozostaje bez zmian.
aggrega servePublikuje go w edytorze jako ostrzeżenie, gdy encja Aggregate jest otwarta. Znacznik wskazuje odwołanie lub wtyczkę, a nie dokument w obszarze roboczym, więc pozostaje przy encji Aggregate; tylko własne błędy mapowania encji Manifest są wyświetlane przy encji Manifest.
Natywne dla AI narzędzie buildZgłasza go i odmawia działania, jeśli skonfigurowano zatrzymanie na tym poziomie ważności.
Natywne dla AI narzędzia describe i validateZgłaszają go obok własnych wyników.

To, czy znacznik także zatrzymuje kompilację, zależy od osobnego ustawienia: build.halt_on_deprecated_severity jest domyślnie nieustawione, więc nic się nie zatrzymuje, a ustawienie go na dany poziom ważności powoduje zatrzymanie na tym poziomie i wyższych. Dotyczy ono kompilacji — aggrega build i natywnego dla AI narzędzia build, które wykonuje tę samą operację — i niczego więcej: miejsca zgłaszające podają znacznik i w każdym przypadku kontynuują działanie. Podniesienie progu nigdy nie ogranicza informacji przekazywanych w żadnym miejscu — nadal otrzymuje się powiadomienie o wszystkim poniżej progu i o wszystkim, czego zatrzymanie nie obejmuje.

Niektóre wtyczki są zapisywane gdzie indziej i stamtąd pochodzą ich znaczniki. Dołączenie plugins.linter oraz dołączenie plugins.governance w roli ir-verdict lub render-verdict nie kształtują żadnej części renderowanego wyniku, więc są przypinane w plugins-trust.yaml obok pliku blokady, a nie w samym pliku blokady. Każdy rekord w nim zawiera znacznik wykryty dla wskazanej wtyczki wraz z jej tożsamością, a aggrega pull zapisuje go tak samo jak znacznik w wierszu pliku blokady.

aggrega build, aggrega lint --release i aggrega validate --release odczytują oba rekordy, więc przestarzała wtyczka jest tam wskazywana tak samo jak przestarzałe odwołanie, a build.halt_on_deprecated_severity dotyczy obu jednakowo. Warto znać dwie różnice. Powiadomienie o takiej wtyczce nie podaje, kiedy zaobserwowano rekord — ten plik nie zawiera żadnych znaczników czasu, dzięki czemu jest odtwarzany bajt w bajt — dlatego zamiast tego podaje źródło informacji i polecenie, które ją odświeża. Ponadto wpis w nim nigdy nie jest nadpisywany przez zwykłe pobranie: nowo opublikowany znacznik jest dodawany do rekordu, który wtyczka już ma, a tożsamość, do której jest przypisana, pozostaje bez zmian, dopóki nie zażąda się jej zmiany za pomocą aggrega pull --upgrade.

retracted to warstwa wycofania i działa również wcześniej. Wersja zapisana jako wycofana jest wykluczana z rozważania, gdy aggrega pull wybiera wersję dla odwołania, które jej nie wskazało. Jeśli inna opublikowana wersja spełnia odwołanie, zostaje ona wybrana, a pobranie to zgłasza, podając pominiętą wersję, zapisany dla niej powód oraz wersję wybraną w zamian. Jeśli nie pozostaje żadna opublikowana wersja spełniająca odwołanie, pobranie zatrzymuje się i informuje, że wszyscy kandydaci zostali wycofani — nie zgłasza encji jako brakującej i nigdy nie wybiera zastępstwa po cichu.

Jawne wskazanie wersji ma pierwszeństwo przed wycofaniem

Odwołanie, które wskazuje dokładną wersję, zawsze rozwiązuje się do tej wersji, niezależnie od tego, czy została ona wycofana. Wskazanie wersji jest nadpisaniem, więc nie istnieje osobne ustawienie wyłączające wykluczenie — i z dokładnie tego samego powodu przypięta wersja z poprzedniego aggrega pull nadal się rozwiązuje.

Gdy wskazana wersja została wycofana, pull informuje o tym wyraźnie, dzięki czemu kompilacja, która już się na nią zdecydowała, nadal działa, a jednocześnie widać, dlaczego warto rozważyć zmianę.

Zapisy wycofań to migawka, a nie bieżąca odpowiedź

Opublikowany artefakt jest niezmienny, ale wycofanie nie: wersja może zostać odwołana po ostatnim sprawdzeniu. Wykluczenie odczytuje to, co obszar roboczy zapisał przy ostatnim budowaniu lokalnego indeksu rejestru, więc chroni przed wyborem wersji, o której wiadomo, że została wycofana. Nie może stwierdzić, że wersja nie jest wycofana w tej chwili.

Każdy raport o znaczniku zapisanym wcześniej podaje, kiedy ten zapis zaobserwowano, dzięki czemu nieaktualny zapis można odróżnić od świeżego, a każdy z nich wskazuje polecenie, które go odświeża. Przechowywane są dwa zapisy i odświeżają się osobno: wykluczenie wersji i aggrega inspect odczytują lokalny indeks rejestru, który odświeża aggrega registry update, natomiast aggrega build odczytuje znacznik zapisany w pliku blokady, który odświeża aggrega pull. To, co aggrega pull wypisuje w trakcie sprawdzania, nie zawiera takiego momentu — informuje o tym, co znalazło właśnie wtedy.

Z tego samego powodu brak wycofania nie dowodzi, że żadne nie istnieje — a jedynie, że żadnego nie zapisano w chwili ostatniego odświeżenia.

Gdzie pojawia się informacja

To, które polecenie informuje o wycofaniu, wynika z tego, który zapis odczytuje. Tabela powyżej dotyczy znacznika zapisanego w pliku blokady — tego, co przypięła ta encja Release. Ta tabela dotyczy lokalnego indeksu rejestru — tego, co opublikował rejestr — czyli zapisu, który odczytuje wykluczenie wersji.

PolecenieCo informuje o zapisanym wycofaniu
aggrega registry updateWymienia każdy znacznik napotkany podczas przeglądania rejestru: repozytorium, wersję, dla której go zapisano, poziom ważności oraz to, czy znacznik został zapisany. Następnie każdy rejestr podaje, ile znaczników zawiera teraz jego indeks.
aggrega searchPodaje wersję, którą wybrałoby rozwiązywanie zamiast wersji wycofanej, i wymienia wycofane wersje w kolumnie NOTES. --include-retracted zamiast tego podaje najwyższą opublikowaną wersję.
aggrega inspectWypisuje pod encją zapisany poziom ważności wraz z wersją, dla której go zapisano, przyczyną, zamiennikiem, jeśli został wskazany, oraz datą wydania — dla każdego rodzaju, który rozwiązuje po nazwie.
aggrega pullWymienia każdą pominiętą wersję, zapisaną dla niej przyczynę oraz wersję wybraną w zamian. Wersja wskazana jawnie nadal jest rozwiązywana, a wycofanie jest ogłaszane, a nie wykonywane.
aggrega plugin addTo samo: wersja, którą wybiera, jest sprawdzana na każdej ze ścieżek, którymi rozwiązuje wersję, a wersja wskazana jako <name>:<version> nadal jest rozwiązywana, z ogłoszeniem wycofania. Jeśli znaczników nie udało się odczytać, informuje o tym i stwierdza, że opublikowane wersje nie zostały sprawdzone.
aggrega buildNic z tego zapisu. Odczytuje wyłącznie plik blokady, nigdy indeks, więc podaje znacznik zapisany dla przypiętej wersji.
aggrega serveNic z tego zapisu. Jego własne rozwiązywanie nie sprawdza zapisów wycofań, więc nadal może w nim zostać wybrana wycofana wersja; znacznik z pliku blokady przekazuje do edytora.

Dwa ostatnie wiersze należy czytać razem z pozostałymi: polecenie informuje o wycofaniu tylko tam, gdzie robi coś, na co wycofanie ma wpływ — wybiera wersję albo pokazuje, co powiedział wydawca. Milczenie polecenia, które nie robi żadnej z tych rzeczy, nie dowodzi, że nic nie zostało zapisane.

Powiadomienie podaje poziom ważności zapisany przez wydawcę. Wycofany artefakt jest zgłaszany jako retracted; dwa poziomy doradcze są zgłaszane jako przestarzałe, ze wskazaniem, o który z nich chodzi. Odczytana informacja odpowiada więc wartości, która została zapisana, oraz wartości, za pomocą której konfiguruje się próg zatrzymania.

Dwa rodzaje powiadomień są rozdzielone, ponieważ dotyczą różnych zdarzeń. Wiersz deprecation: mówi coś o artefakcie. Wiersz retraction: mówi, czego nie otrzymano — o wersji, która została pominięta, albo o sprawdzeniu, którego nie udało się wykonać. Jeśli jedno polecenie emituje oba o tym samym artefakcie, są to dwa fakty, a nie jedno stwierdzenie powtórzone dwukrotnie.

Które rozwiązania obejmuje wykluczenie

Wykluczenie działa wszędzie tam, gdzie polecenie wybiera wersję za użytkownika. Taka jest reguła i to ona rozstrzyga, czy dane rozwiązanie jest objęte wykluczeniem.

aggrega pull stosuje je wszędzie tam, gdzie wybiera wersję dla odwołania, które jej nie wskazało — niezależnie od tego, co odwołanie wskazuje: encję katalogu, bibliotekę, opublikowaną encję Aggregate. Wszystkimi rządzi jedna reguła, więc wersja, do której rozwiązuje się odwołanie, nie zależy od rodzaju odwołania, które o nią poprosiło.

aggrega plugin add stosuje je na każdej ścieżce, którą rozwiązuje nieprzypięte odwołanie do pluginu: względem opublikowanych wersji, które już zawiera lokalny indeks rejestru, oraz względem bieżącej listy wersji, po którą sięga, gdy indeks nie zawiera danego repozytorium. Wycofana wersja jest pomijana, a zamiana ogłaszana, niezależnie od ścieżki, która ją rozwiązała.

Wyjątkiem jest demon obsługujący edytor. Rozwiązuje on odwołania na żądanie, gdy obsługuje edytor, a to rozwiązanie wybiera wersje bez sprawdzania zapisów o wycofaniu, więc wersja zapisana jako wycofana (retracted) nadal może zostać tam wybrana.

Tam, gdzie nic nie jest wybierane, wykluczenie nie ma na co działać: odwołanie wskazujące dokładną wersję rozwiązuje się do tej wersji, a wycofanie jest ogłaszane, lecz nie jest stosowane. Nic z tego nie zmienia też informacji przekazywanych w czasie budowania — aggrega build zgłasza każdy znacznik zapisany w pliku blokady, niezależnie od tego, która ścieżka przypięła wersję.

Zobacz także

  • ./aggrega-sign.md — znacznik jest podpisywany własnym skrótem (digest), więc tryby podpisywania i poświadczenia wymagane przez każdy z nich są takie, jak opisano tam.
  • ./aggrega-serve.md — demon dołącza ten sam znacznik pod aggrega/deprecateArtifact. Treść, o którą terminal prosi interaktywnie, jest tam wymagana w żądaniu, ponieważ nic w tym interfejsie nie może o nią zapytać.
  • ./aggrega-mcp.md — ta sama funkcja jako narzędzie deprecate-artifact, które może wywołać asystent. Przed zezwoleniem na nie należy przeczytać, co ta strona mówi o jego dopuszczaniu: wycofanie zmienia to, do czego rozwiązuje każdy konsument tego rejestru.