aggrega deprecate
Приєднати підписану позначку застарілості до вже опублікованого артефакту
Синтаксис
aggrega deprecate <reference> [flags]Опис
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.Прапорці
| Прапорець | За замовчуванням | Опис |
|---|---|---|
--from | — | Пакетний файл (YAML або JSON як його підмножина), список верхнього рівня якого приєднує одну позначку на кожен запис. Кожен запис містить посилання, рівень серйозності та причину, а також необов’язкові заміну й повідомлення. Взаємовиключний із позиційним посиланням і з —severity, —reason, —replacement та —message. |
--fulcio-url | — | URL центру сертифікації Fulcio для безключового підписування. Якщо не вказано, використовується загальнодоступний екземпляр Fulcio. |
--identity-token | — | Токен ідентичності OIDC для безключового підписування. Необов’язковий в інтерактивному терміналі (його отримує процес у браузері) і в GitHub Actions (токен OIDC робочого процесу випускається автоматично); обов’язковий для іншого неінтерактивного використання або використання в CI, де його натомість можна експортувати як AGGREGA_IDENTITY_TOKEN або SIGSTORE_ID_TOKEN. |
--key | — | Шлях до наявного закритого ключа ECDSA P-256 у форматі PEM для офлайн-підписування ключем. Якщо не вказано, використовується безключове підписування. |
--message | — | Необов’язкове повідомлення, що зберігається для аудиту та для записаної діагностики під час збирання; якщо не задано, типово дорівнює —reason. Відхиляється разом із —from, записи якого містять власне. |
--reason | — | Зрозуміла людині причина застарілості — чому артефакт застарів і що робити натомість. Обов’язкова з позиційним посиланням, якщо її не надає інтерактивний запит; відхиляється разом із —from, записи якого містять власну. |
--rekor-url | — | URL журналу прозорості Rekor для безключового підписування. Якщо не вказано, використовується загальнодоступний екземпляр Rekor. |
--replacement | — | Необов’язкове посилання на артефакт, що замінює застарілий. Відхиляється разом із —from, записи якого містять власне. |
--severity | — | Рівень серйозності застарілості: одне з warning, error, retracted. Обов’язковий із позиційним посиланням, якщо його не надає інтерактивний запит; відхиляється разом із —from, записи якого містять власний. |
--timestamp-url | — | Необов’язковий URL центру позначок часу RFC3161 для безключового підписування. |
Звідки беруться кінцеві точки підписування
URL-адреси Fulcio і Rekor для безключового підписування та шлях до ключа для підписування ключем також можуть надходити з блоку signing: у .aggrega-config.yaml (глобального та для окремого реєстру, де значення, задане для реєстру артефакту, має перевагу над глобальним, поле за полем); прапорець перевизначає конфігурацію, а конфігурація перевизначає загальнодоступне типове значення. Тож загальнодоступні екземпляри, названі в таблиці прапорців, використовуються лише тоді, коли ні прапорець, ні конфігурація вашого робочого простору не називає кінцевої точки. Маркер підписується точно так само, як aggrega sign підписує артефакт.
Коли реєстр не виконує запис
Позначення артефакту застарілим записує до реєстру двічі: спочатку позначку, приєднану як referrer артефакту, а потім підпис позначки, приєднаний як referrer позначки. Кожен запис повторюється, коли реєстр або мережа не виконує його так, що наступна спроба може бути успішною, наприклад через помилку сервера, тайм-аут або скинуте
з’єднання; aggrega push
перелічує такі збої. Запис виконується щонайбільше три рази, з інтервалом пів секунди, а потім
секунда, і кожна спроба — це нове завантаження тих самих байтів, а не
повторне надсилання запиту, що не вдався. Часова мітка позначки ставиться один раз, перед
першою спробою, тому повторений запис залишає одну позначку й один підпис, а не два.
Підписування позначки, що відбувається між двома записами, не повторюється як ціле; усередині безключового підписування запит, на який центр сертифікації, журнал прозорості або служба позначок часу відповідає 429 Too Many Requests чи помилкою сервера, надсилається цій службі повторно, як описано в aggrega sign. Запис, який усе ще не вдається після останньої спроби, або невдале підписування зупиняє команду й називає крок; позначка, уже приєднана на той момент, залишається приєднаною без підпису. З --from записи, приєднані до того, що не вдався, залишаються приєднаними.
Пакетний файл містить вміст кожної позначки
З --from рівень серйозності, причина, заміна й повідомлення кожної позначки беруться з її власного запису в пакетному файлі. Тому --severity, --reason, --replacement чи --message, передані разом із --from, відхиляються, а не ігноруються: команда називає кожен переданий прапорець і зупиняється до того, як пакетний файл буде прочитано, тож жодна позначка не приєднується. Розмістіть вміст у записах файлу або позначте застарілим одне посилання за допомогою його прапорців вмісту.
Пакет підписується одними обліковими даними
З --from кожен маркер у файлі пакета підписується тими самими обліковими даними:
одним наявним ключем або однією безключовою ідентичністю, яку запитують один раз для всього файлу.
Які з них потрібні запису, визначає конфігурація для реєстру його посилання — signing.key_path, що застосовується до цього реєстру, вибирає ключ, який він
називає, а якщо жоден не застосовується, маркер підписується без ключа. Коли записам
потрібні різні облікові дані — конфігурація називає ключ для одного реєстру й
жодного для іншого або два різні ключі, — жоден маркер не прикріплюється, а команда
називає реєстри з кожного боку. Вона робить це до запиту будь-якої ідентичності та
до читання будь-якого реєстру.
Розділіть файл на окремий пакет для кожних облікових даних або передайте один ключ через --key, який
застосовується до кожного запису незалежно від того, що конфігурація каже для кожного реєстру. Це
повідомлення описано в розділі
References signed together need different signing credentials (Посиланням, що підписуються разом, потрібні різні облікові дані для підпису).
Підписувач кожного запису також готується до прикріплення першого маркера, тож ключ, який не вдається прочитати, або наданий токен ідентичності без придатного суб’єкта зупиняє пакет, не прикріпивши нічого.
Що робить кожен рівень серйозності
Три рівні серйозності утворюють упорядковану множину — warning, потім error, потім
retracted — і поділяються на два яруси, які відрізняються тим, коли вони діють.
warning і error — дорадчі яруси. Маркер будь-якого з цих рівнів ніколи
не змінює версію, до якої розв’язується посилання. Його записують, коли ви запускаєте
aggrega pull, і кожен інструмент, що читає lockfile, повідомляє про нього.
Кожен із цих інструментів повідомляє про кожне застаріле посилання, яке закріплює lockfile, незалежно від рівня серйозності, називаючи посилання, його рівень, його повідомлення і час, коли запис було зафіксовано:
| Інструмент | Що він робить із записаним маркером |
|---|---|
aggrega build | Повідомляє про нього і зупиняється, якщо ви налаштували зупинку на цьому рівні. |
aggrega validate --release | Повідомляє про нього. Вердикт не змінюється. |
aggrega lint --release | Повідомляє про нього. Вердикт не змінюється. |
aggrega serve | Публікує його у вашому редакторі як попередження, поки відкрито Aggregate. Маркер указує на посилання або плагін, а не на документ у вашому робочому просторі, тож він залишається на сутності Aggregate; на сутності Manifest показуються лише її власні помилки зіставлення. |
AI-native інструмент build | Повідомляє про нього і відмовляє, якщо ви налаштували зупинку на цьому рівні. |
AI-native інструменти describe і validate | Повідомляють про нього разом із власним виводом. |
Чи маркер також зупиняє збирання — окреме налаштування:
build.halt_on_deprecated_severity типово не задано, тож ніщо не зупиняється, а
якщо задати йому рівень серйозності, збирання зупиняється на цьому рівні й вищих. Воно керує збиранням —
aggrega build та AI-native інструментом build, який виконує ту саму операцію, — і
більше нічим: інструменти звітування називають маркер і продовжують роботу в будь-якому разі.
Підвищення порогу ніколи не зменшує того, що вам повідомляють, на жодному інструменті — ви все одно
отримуєте сповіщення про все нижче порогу і про все, чого зупинка не
охоплює.
Деякі плагіни записуються деінде, і їхні маркери надходять звідти.
Під’єднання plugins.linter і під’єднання plugins.governance у ролі
ir-verdict або render-verdict не впливають на жоден згенерований вивід, тому їх
закріплюють у plugins-trust.yaml поруч із
lockfile, а не в самому lockfile. Кожен запис там містить маркер,
виявлений для плагіна, який він називає, разом із його ідентичністю, і aggrega pull
записує його так само, як записує маркер у рядку lockfile.
aggrega build, aggrega lint --release і aggrega validate --release читають
обидва записи, тож застарілий плагін там називається так само, як застаріле
посилання, а build.halt_on_deprecated_severity однаково керує обома. Варто знати дві
відмінності. Сповіщення для такого плагіна не вказує, коли
запис було зафіксовано, — цей файл узагалі не містить часових позначок, саме тому
він відтворюється байт у байт, — тож натомість воно називає джерело факту й команду,
яка його оновлює. І запис там ніколи не перезаписується звичайним
pull: новоопублікований маркер додається до запису, який плагін уже має,
а ідентичність, до якої його прив’язано, лишається незмінною, доки ви не попросите її змінити за допомогою
aggrega pull --upgrade.
retracted — ярус відкликання, і він діє ще й раніше. Версію,
записану як відкликану, вилучають із розгляду, коли aggrega pull
обирає версію для посилання, яке її не називає. Якщо інша опублікована
версія задовольняє посилання, береться ця версія, і pull про це повідомляє,
називаючи пропущену версію, записану щодо неї причину і версію, яку він
узяв натомість. Якщо не лишилося жодної опублікованої версії, що задовольняє посилання, pull
зупиняється й повідомляє, що всіх кандидатів відкликано, — він не повідомляє про
сутність як відсутню і ніколи мовчки не відкочується до іншого варіанта.
Явне зазначення версії скасовує відкликання
Посилання, що зазначає точну версію, завжди розв’язується саме в цю версію, незалежно
від того, чи її було відкликано. Зазначення версії і є скасуванням, тому окремого
параметра для вимкнення виключення немає — і закріплена версія з попереднього
aggrega pull продовжує розв’язуватися з тієї самої причини.
Якщо зазначену вами версію було відкликано, pull явно про це повідомляє, тож збірка, яка вже на неї покладається, продовжує працювати, а ви водночас бачите, чому вам, можливо, варто перейти на іншу.
Записи про відкликання — це знімок, а не актуальна відповідь
Опублікований артефакт незмінний, але відкликання — ні: версію можуть відкликати після того, як ви востаннє перевіряли. Виключення читає те, що ваш робочий простір записав, коли востаннє будував свій локальний індекс реєстру, тож воно захищає вас від вибору версії, про яку відомо, що її відкликано. Воно не може сказати вам, що версію не відкликано саме зараз.
Кожне повідомлення про раніше записаний маркер зазначає, коли цей запис було зафіксовано, тож
застарілий запис можна відрізнити від свіжого, і кожне називає команду, яка
його оновлює. Зберігаються два записи, і вони оновлюються окремо: виключення версій
і aggrega inspect читають ваш локальний індекс реєстру, який оновлює aggrega registry update,
тоді як aggrega build читає маркер, записаний у lock-файлі, який оновлює
aggrega pull. Те, що aggrega pull виводить під час пошуку, не містить
такого моменту — вона повідомляє те, що знайшла саме тоді.
З тієї ж причини відсутність відкликання не доводить, що його немає, — лише те, що жодного не було записано, коли ви востаннє оновлювали дані.
Де вам про це повідомляють
Яка команда повідомляє вам про відкликання, залежить від того, який запис вона читає. Таблиця вище стосується маркера, записаного у вашому lock-файлі, — того, що закріпила ця сутність Release. Ця таблиця стосується локального індексу реєстру — того, що опублікував реєстр, — тобто запису, який читає виключення версій.
| Команда | Що вона повідомляє про записане відкликання |
|---|---|
aggrega registry update | Називає кожен маркер, який трапляється під час обходу реєстру: репозиторій, версію, для якої його записано, рівень серйозності та те, чи було маркер записано. Потім кожен реєстр повідомляє, скільки маркерів тепер містить його індекс. |
aggrega search | Показує версію, яку вибрало б розв’язання, а не відкликану, і називає відкликані версії в стовпці NOTES. З --include-retracted натомість показує найвищу опубліковану версію. |
aggrega inspect | Виводить під сутністю записаний рівень серйозності разом із версією, для якої його записано, причиною, заміною, якщо її вказано, і датою видачі — для кожного типу, який вона розв’язує за назвою. |
aggrega pull | Називає кожну пропущену версію, записану для неї причину та версію, яку вибрано натомість. Явно вказана вами версія все одно розв’язується, а про відкликання лише повідомляється, без дій щодо нього. |
aggrega plugin add | Те саме: версія, яку вона обирає, перевіряється на будь-якому зі шляхів, якими вона розв’язує версію, а версія, яку ви називаєте як <name>:<version>, усе одно розв’язується, з оголошенням про відкликання. Якщо маркери не вдалося прочитати, вона про це повідомляє і зазначає, що опубліковані версії не перевірялися. |
aggrega build | Нічого з цього запису. Вона читає лише ваш lock-файл і ніколи не читає індекс, тож повідомляє маркер, записаний для закріпленої вами версії. |
aggrega serve | Нічого з цього запису. Її власне розв’язання не звертається до записів про відкликання, тож там усе ще може бути вибрано відкликану версію; маркер із lock-файлу вона передає у ваш редактор. |
Останні два рядки слід читати разом з іншими: команда повідомляє про відкликання лише тоді, коли виконує щось, чого відкликання стосується, — вибирає версію або показує вам, що сказав видавець. Мовчання команди, яка не робить ні того, ні іншого, не свідчить про те, що нічого не записано.
Сповіщення називає рівень серйозності, який записав видавець. Про відкликаний артефакт повідомляється як retracted; два рекомендаційні рівні серйозності повідомляються як застарілі, із зазначенням, який саме з двох. Тож те, що ви читаєте, збігається зі значенням, яке було задано автором, і зі значенням, яким ви налаштували б поріг зупинки.
Два види сповіщень розрізняються, бо повідомляють про різні події. Рядок deprecation: повідомляє вам щось про артефакт. Рядок retraction: повідомляє, чого ви не отримали, — пропущену версію або перевірку, яку не вдалося виконати. Якщо одна команда виводить обидва щодо того самого артефакту, це два факти, а не одне твердження, повторене двічі.
Які розв’язання охоплює виключення
Виключення діє скрізь, де команда обирає версію за вас. Це правило, і воно визначає, чи охоплено будь-яке конкретне розв’язання.
aggrega pull застосовує його скрізь, де обирає версію для посилання, яке її не назвало, — хоч би що це посилання називало: сутність каталогу, бібліотеку,
опубліковану сутність Aggregate. Одне правило керує всіма ними, тож версія, до якої розв’язується посилання,
не залежить від того, який різновид посилання її запитав.
aggrega plugin add застосовує його на кожному маршруті, яким розв’язує незакріплене посилання на плагін:
щодо опублікованих версій, які вже містить ваш локальний індекс реєстру, і щодо актуального списку версій, до якого
вона звертається, коли цей індекс не містить репозиторію. Відкликану версію пропускають, а про заміну
повідомляють, хоч би яким маршрутом її розв’язано.
Виняток становить демон, що працює з редактором. Він розв’язує посилання на вимогу, поки обслуговує редактор, і це розв’язання обирає версії, не звертаючись до записів про відкликання, тож версію, записану як відкликану, там усе ще можуть обрати.
Там, де нічого не вибирається, виключенню немає на що діяти: посилання,
що вказує точну версію, розв’язується в цю версію, а про відкликання повідомляється,
але воно не застосовується. Так само ніщо з цього не змінює того, що вам повідомляють під час збирання, —
aggrega build звітує про кожен маркер, записаний у lock-файлі, незалежно від того, яким шляхом
закріплено версію.
Див. також
- ./aggrega-sign.md — маркер підписується власним дайджестом, тому режими підписування та облікові дані, потрібні кожному з них, — ті, що описані там.
- ./aggrega-serve.md — демон додає той самий маркер через
aggrega/deprecateArtifact. Вміст, який у терміналі запитується в користувача, там є обов’язковим у запиті, бо ніщо на цьому інтерфейсі не може його запитати. - ./aggrega-mcp.md — та сама можливість у вигляді інструмента
deprecate-artifact, який може викликати асистент. Перш ніж дозволити це, прочитайте, що про це сказано на тій сторінці: відкликання змінює те, що отримує під час розв’язання кожен споживач цього реєстру.