aggrega push-artifact
Публикация отдельного артефакта данных (например, пакета документации) в реестр OCI
Синтаксис
aggrega push-artifact <file> [flags]Описание
Publish a standalone data artifact — a documentation bundle or any other non-entity blob — to an OCI registry under the reserved docs/ namespace. Unlike push, which bundles a catalog entity and dispatches on its kind, push-artifact carries opaque bytes: it reads the file, packs it under the given media type (defaulting to the documentation-bundle media type), and tags it at docs/<name>:<tag>. The published artifact is signed separately by reference with aggrega sign. Beside it, push-artifact states when it published, as a small published-at attachment carrying this machine's clock in UTC to the second; the attachment moves no digest and changes no tag.Флаги
| Флаг | По умолчанию | Описание |
|---|---|---|
--dry-run | false | Вычислить ссылку и вывести предлагаемый |
--media-type | application/vnd.aggrega.docs.v1beta1+tar+gz | Тип носителя артефакта OCI; по умолчанию — тип носителя пакета документации |
--name | — | Имя артефакта в зарезервированном пространстве имён docs/ (например, «aggrega-docs» публикуется в docs/aggrega-docs) |
--registry | — | Хост целевого реестра (переопределяет default_registry рабочего пространства) |
--tag | — | Тег версии, под которым публикуется артефакт (обязательный) |
Артефакт пакета документации
Пакет документации — это отдельный артефакт данных (tar-архив отрисованной документации, сжатый gzip), а не сущность каталога. Он имеет тип носителя application/vnd.aggrega.docs.v1beta1+tar+gz — это тип артефакта, который видит потребитель при получении пакета из реестра.
Пакеты публикуются в сегменте репозитория docs/: --name aggrega-docs помещает
артефакт в docs/aggrega-docs, а --tag выбирает версию, поэтому координата для получения —
<registry>/docs/<name>:<tag>, например
hub.aggrega.ai/docs/aggrega-docs:1.0.0. Поскольку пакет — обычный артефакт
данных, а не сущность каталога, его можно получить любым OCI-совместимым клиентом
по этой ссылке и типу носителя. Опубликованный файл носит имя, заданное
в --name, поэтому клиент, записывающий файлы по имени, запишет его под этим именем:
oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 оставляет aggrega-docs в
текущем каталоге, байт в байт таким, каким он был опубликован.
Когда реестр не выполняет запись
Публикация записывает в реестр по шагам — файл, манифест, который
его называет, тег, а затем рядом с ним дату публикации, — и каждая из этих
записей повторяется, если реестр или сеть отклоняют её так, что последующая
попытка может завершиться успешно, например при ошибке сервера, тайм-ауте или сбросе соединения;
aggrega push перечисляет эти
сбои. Запись выполняется не более трёх раз, с интервалом в полсекунды, а затем в секунду,
и каждая попытка — это новая загрузка тех же байтов, а не повторная отправка
неудавшегося запроса, поэтому повторённая запись даёт тот же результат, что и одна попытка.
Если запись не удалась и после последней попытки, команда завершается с ошибкой, и ошибка называет шаг. Сбой при добавлении даты происходит после того, как артефакт записан: артефакт остаётся опубликованным, а команда завершается с ненулевым кодом, сообщая, что дату публикации добавить не удалось. Повторный запуск той же публикации завершает её: артефакт отмечается как уже опубликованный, ничего не загружается, а дата добавляется, если у артефакта её нет, и отражает время часов этого запуска — момент, когда публикация была завершена. К артефакту, у которого дата уже указана, ничего не добавляется, а если список прочитать не удаётся, команда завершается с ненулевым кодом, ничего не добавив.
Автономный режим
Публикация артефакта требует обращения к сети, поэтому в автономном режиме — заданном ключом верхнего уровня offline в файле конфигурации, AGGREGA_OFFLINE или --offline — эта команда отказывается работать ещё до чтения файла, и в сообщении об отказе указано, какой из этих трёх способов задал режим. --dry-run продолжает работать, так как он лишь вычисляет ссылку и не выполняет вызовов. Чтобы выполнить публикацию в одном запуске из автономного рабочего пространства, передайте --offline=false.
См. также
- ./aggrega-sign.md — артефакт данных подписывается постфактум, по ссылке; эта команда сама подпись не добавляет.
- ./aggrega-serve.md — демон предоставляет ту же публикацию через
aggrega/publishArtifact, поэтому редактор может выполнить её, не покидая сеанса. - ./aggrega-mcp.md — та же возможность в виде инструмента
publish-artifact, который может вызвать ассистент. Прежде чем разрешать его, прочитайте, что об этом сказано на той странице.