Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

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 как его подмножество), список верхнего уровня которого прикрепляет по одной отметке на каждый элемент. Каждый элемент содержит reference, severity и reason, а также необязательные replacement и message. Взаимоисключающий с позиционной ссылкой и с —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, и о нём сообщает каждая точка вывода, читающая lock-файл.

Каждая из этих точек вывода сообщает о каждой устаревшей ссылке, закреплённой в lock-файле, независимо от уровня серьёзности, указывая ссылку, её уровень серьёзности, её сообщение и время, когда запись была получена:

Точка выводаЧто она делает с записанным маркером
aggrega buildСообщает о нём и останавливается, если для этого уровня серьёзности настроена остановка.
aggrega validate --releaseСообщает о нём. Вердикт не меняется.
aggrega lint --releaseСообщает о нём. Вердикт не меняется.
aggrega serveПубликует его в вашем редакторе как предупреждение, пока открыт Aggregate. Маркер указывает на ссылку или плагин, а не на документ в вашем рабочем пространстве, поэтому он остаётся на сущности Aggregate; на сущности Manifest показываются только её собственные ошибки сопоставления.
ИИ-инструмент buildСообщает о нём и отказывает в выполнении, если для этого уровня серьёзности настроена остановка.
ИИ-инструменты describe и validateСообщают о нём вместе со своим собственным выводом.

Останавливает ли маркер ещё и сборку — отдельная настройка: build.halt_on_deprecated_severity по умолчанию не задан, поэтому ничто не останавливается, а если задать в нём уровень серьёзности, остановка происходит на этом уровне и выше. Она управляет сборкой — aggrega build и ИИ-инструментом сборки, который выполняет ту же операцию, — и ничем больше: точки вывода сообщений называют маркер и в любом случае продолжают работу. Повышение порога никогда не сокращает того, что вам сообщается, ни в одной точке вывода — вы по-прежнему получаете уведомление обо всём, что ниже порога, и обо всём, что остановка не охватывает.

Некоторые плагины записываются в другом месте, и их маркеры берутся оттуда. Подключение plugins.linter, а также подключение plugins.governance в роли ir-verdict или render-verdict никак не влияют на результат рендеринга, поэтому они закрепляются в plugins-trust.yaml рядом с lock-файлом, а не в самом lock-файле. Каждая запись там содержит маркер, обнаруженный для указанного в ней плагина, вместе с его идентичностью, и aggrega pull записывает его так же, как записывает маркер в строке lock-файла.

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 выводит во время поиска, такого момента не содержит — команда сообщает то, что нашла именно в этот момент.

По той же причине отсутствие отзыва не доказывает, что его нет, — лишь то, что ни одного отзыва не было записано при вашем последнем обновлении.

Где вы об этом узнаёте

Какая команда сообщает вам об отзыве, зависит от того, какую запись она читает. Таблица выше охватывает маркер, записанный в вашем lockfile, — то, что закрепила эта сущность Release. Эта таблица охватывает локальный индекс реестра — то, что опубликовал реестр, — а это та запись, которую читает исключение версий.

КомандаЧто она сообщает о записанном отзыве
aggrega registry updateНазывает каждый маркер, встреченный при обходе реестра: репозиторий, версию, для которой он записан, уровень серьёзности и то, был ли маркер записан. Затем каждый реестр сообщает, сколько маркеров теперь содержит его индекс.
aggrega searchСообщает версию, которую выбрало бы разрешение, а не отозванную, и называет отозванные версии в столбце NOTES. С --include-retracted вместо этого сообщается самая высокая опубликованная версия.
aggrega inspectВыводит под сущностью записанный уровень серьёзности вместе с версией, для которой он записан, причиной, заменой, если она указана, и датой выпуска — для каждого вида, который она разрешает по имени.
aggrega pullНазывает каждую пропущенную версию, записанную для неё причину и версию, выбранную вместо неё. Версия, которую вы назвали явно, по-прежнему разрешается, а об отзыве сообщается, но он не применяется.
aggrega plugin addТо же самое: версия, которую она выбирает, проверяется на любом из путей, которыми она разрешает версию, а версия, которую вы указываете как <name>:<version>, по-прежнему разрешается, с объявлением об отзыве. Если маркеры не удалось прочитать, она сообщает об этом и указывает, что опубликованные версии не были проверены.
aggrega buildНичего из этой записи. Она читает только ваш lockfile и никогда не читает индекс, поэтому сообщает маркер, записанный для закреплённой вами версии.
aggrega serveНичего из этой записи. Её собственное разрешение не обращается к записям об отзыве, поэтому там всё ещё может быть выбрана отозванная версия; маркер из lockfile она передаёт в ваш редактор.

Читайте две последние строки вместе с остальными: команда сообщает вам об отзыве только там, где она делает что-то, к чему отзыв имеет отношение, — выбирает версию или показывает, что сказал издатель. Молчание команды, которая не делает ни того, ни другого, не свидетельствует о том, что ничего не записано.

Уведомление называет уровень серьёзности, записанный издателем. Об отозванном артефакте сообщается как о 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, который может вызывать ассистент. Прежде чем разрешать его, прочитайте, что об этом сказано на той странице: отзыв меняет то, во что разрешаются ссылки у каждого потребителя этого реестра.