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
| Flaga | Domyślnie | Opis |
|---|---|---|
--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:
| Miejsce | Co robi z zapisanym znacznikiem |
|---|---|
aggrega build | Zgłasza go i zatrzymuje się, jeśli skonfigurowano zatrzymanie na tym poziomie ważności. |
aggrega validate --release | Zgłasza go. Werdykt pozostaje bez zmian. |
aggrega lint --release | Zgłasza go. Werdykt pozostaje bez zmian. |
aggrega serve | Publikuje 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 build | Zgłasza go i odmawia działania, jeśli skonfigurowano zatrzymanie na tym poziomie ważności. |
Natywne dla AI narzędzia describe i validate | Zgł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.
| Polecenie | Co informuje o zapisanym wycofaniu |
|---|---|
aggrega registry update | Wymienia 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 search | Podaje 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 inspect | Wypisuje 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 pull | Wymienia 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 add | To 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 build | Nic z tego zapisu. Odczytuje wyłącznie plik blokady, nigdy indeks, więc podaje znacznik zapisany dla przypiętej wersji. |
aggrega serve | Nic 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.