aggrega push-artifact
Publicar un artefacto de datos independiente (como un paquete de documentación) en un registry OCI
Sinopsis
aggrega push-artifact <file> [flags]Descripción
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.Flags
| Flag | Predeterminado | Descripción |
|---|---|---|
--dry-run | false | Calcula la referencia e imprime el |
--media-type | application/vnd.aggrega.docs.v1beta1+tar+gz | Tipo de medio del artefacto OCI; de forma predeterminada, el tipo de medio del paquete de documentación |
--name | — | Nombre del artefacto dentro del espacio de nombres reservado docs/ (p. ej., «aggrega-docs» se publica en docs/aggrega-docs) |
--registry | — | Host del registro de destino (anula el default_registry del workspace) |
--tag | — | Etiqueta de versión con la que publicar el artefacto (obligatoria) |
El artefacto del paquete de documentación
Un paquete de documentación es un artefacto de datos independiente —un tar comprimido con gzip de documentación renderizada— en lugar de una entidad de catálogo. Lleva el tipo de medio application/vnd.aggrega.docs.v1beta1+tar+gz, que es el tipo de artefacto que ve un consumidor al obtener el paquete del registro.
Los paquetes se publican bajo el segmento de repositorio docs/: --name aggrega-docs coloca el artefacto en docs/aggrega-docs, y --tag selecciona la versión, de modo que la coordenada de pull es <registry>/docs/<name>:<tag>; por ejemplo, hub.aggrega.ai/docs/aggrega-docs:1.0.0. Como el paquete es un simple artefacto de datos y no una entidad de catálogo, se obtiene con cualquier cliente compatible con OCI usando esa referencia y ese tipo de medio. El archivo publicado lleva el nombre indicado con --name, de modo que un cliente que escribe archivos por nombre lo escribe con ese nombre: oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 deja aggrega-docs en el directorio actual, byte a byte tal como se publicó.
Cuando el registro hace fallar una escritura
La publicación escribe en el registro en pasos —el archivo, el manifiesto que lo nombra, la etiqueta y luego la fecha de publicación junto a él—, y cada una de esas escrituras se reintenta cuando el registro o la red la hacen fallar de un modo en que un intento posterior puede tener éxito, como un error del servidor, un tiempo de espera agotado o una conexión restablecida; aggrega push enumera esos fallos. Una escritura se intenta como máximo tres veces, con medio segundo y luego un segundo de separación, y cada intento es una nueva subida de los mismos bytes en lugar de un reenvío de la solicitud que falló, de modo que una escritura reintentada deposita lo que habría depositado un único intento.
Una escritura que sigue fallando tras su último intento hace fallar el comando, y el error indica el paso. Un fallo al adjuntar la fecha se produce después de que el artefacto se haya depositado: el artefacto sigue publicado, y el comando termina con un código distinto de cero indicando que no se pudo adjuntar su fecha de publicación. Ejecutar de nuevo la misma publicación la completa: el artefacto se informa como ya publicado, no se sube nada, y la fecha se adjunta donde el artefacto no tiene ninguna, indicando el reloj de esa ejecución, es decir, el momento en que se completó la publicación. A un artefacto que ya indica una fecha no se le adjunta nada, y una lista que no se puede leer termina con un código distinto de cero sin adjuntar nada.
Sin conexión
Publicar un artefacto es un viaje de ida y vuelta por la red, así que en el modo sin conexión —la clave de nivel superior offline en un archivo de configuración, AGGREGA_OFFLINE o --offline— este comando se niega antes de leer el archivo, y el rechazo indica cuál de esos tres estableció el modo. --dry-run sigue funcionando, porque calcula la referencia y no hace ninguna llamada. Para publicar durante una sola ejecución desde un workspace sin conexión, pasa --offline=false.
Véase también
- ./aggrega-sign.md — un artefacto de datos se firma a posteriori, por referencia; este comando no adjunta ninguna firma propia.
- ./aggrega-serve.md — el daemon ofrece la misma publicación en
aggrega/publishArtifact, de modo que un editor puede ejecutarla sin salir de la sesión. - ./aggrega-mcp.md — la misma capacidad como la herramienta
publish-artifact, a la que puede llamar un asistente. Lee lo que esa página dice sobre permitirla antes de hacerlo.