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 | — | Тег версії, під яким публікується артефакт (обов’язковий) |
Артефакт пакета документації
Пакет документації — це окремий артефакт даних (стиснутий gzip архів tar зі згенерованою документацією), а не сутність каталогу. Він має медіатип 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, який може викликати асистент. Перш ніж дозволити його, прочитайте, що про це сказано на тій сторінці.