aggrega push
aggrega push publica una entidad de catálogo en un registro OCI, donde otros workspaces pueden resolverla con aggrega pull.
Qué hace
aggrega push lee un único YAML de entidad, lo empaqueta para el transporte y lo envía a <registry>/<kind>/<metadata.name>:<metadata.version>, con la ruta del repositorio en minúsculas; una Recipe o una FeatureRecipe lleva su spec.capability, y un Plugin su metadata.pluginType, como un segmento entre el tipo y el nombre. Ejecuta aggrega push --list-kinds para obtener los tipos de entidad que publica el binario instalado: un tipo por línea, ordenados, y nada más, de modo que un script puede leerlo directamente. El conjunto abarca los tipos de autoría del catálogo junto con el Aggregate, un módulo reutilizable, y el Plugin, una referencia direccionada por contenido a un artefacto WebAssembly que el compilador enruta y el runtime ejecuta. El Plugin es un artefacto publicable estructural, no un tipo de autoría del catálogo. La publicabilidad es una propiedad de la entidad, no de cómo se usa: un Aggregate es publicable tanto si después se referencia como el spec.aggregate de nivel superior de una Release como si se anida en el bloque aggregates: de otro Aggregate. Release y Manifest son entradas del lado del despliegue, no artefactos de catálogo, y se rechazan.
Empaquetado
Un push publica el documento de la entidad y los archivos que la propia entidad nombra junto a él, y nada más de su directorio. Los archivos que nombra una entidad son:
- para una Recipe o una FeatureRecipe, su
source:local —un directorio viaja con cada archivo que contiene y que conservan las reglas de exclusión registradas en suentity.lock, como describe Qué archivos se distribuyen con una entidad—; cada archivo que sus entradasvaluesMapping:,workload:yartifacts:importan con$import:; y elentity.lockjunto a ella; - para un Component o una Feature, cada archivo de esquema que su
spec.schema, un pilar o un socketusesSchemaimporta con$import:, incluido cada archivo que un archivo importado importa a su vez.
Un Aggregate, un Plugin y los tipos de biblioteca no nombran ningún archivo junto a su documento. Una nota, un README, los archivos de otra entidad o la salida de un build que estén en el directorio no se publican, se llamen como se llamen. Un enlace simbólico entre los archivos que nombra una entidad se rechaza en lugar de seguirse —A symbolic link sits among the files an entity carries (Hay un enlace simbólico entre los archivos que lleva una entidad)—, y lo mismo ocurre con una ruta que una entidad nombra a través de un directorio que es un enlace que sale del directorio de la entidad, antes de empaquetar nada —A path names content outside the entity’s own directory (Una ruta nombra contenido fuera del directorio propio de la entidad).
La forma se deriva de ello. Una entidad que no nombra nada se publica como su documento, sin cambios, con el tipo de medio +yaml de su tipo. Una que nombra un archivo se publica como un .tar.gz que contiene el documento y esos archivos en sus posiciones dentro del directorio, con el tipo de medio +tar+gz de su tipo. Así, una Recipe cuyo contenido está todo en línea se publica como su documento, y un Component cuyo esquema se importa de un archivo se publica como un archivo comprimido. Catálogo y registro §6 enumera ambos tipos de medio para cada tipo.
Cada archivo de un archivo comprimido lleva el modo 0644 y ninguna marca de tiempo, sean cuales sean sus bits de permiso en disco. Un checkout escribe los archivos con sus propios bits de permiso, y un sistema que no registra ningún bit de ejecución extrae como archivo normal lo que otro sistema extrae como ejecutable, de modo que el archivo comprimido no lleva ningún modo leído del disco: dos checkouts de un mismo commit publican los mismos archivos sea cual sea su umask y en cualquier sistema en que se hayan hecho, y cambiar el bit de ejecución de un script no cambia nada de lo que se publica.
Un push advierte de cada entrada de un archivo comprimido que Windows no puede contener tal como está escrita: una ruta con una parte que lleva el nombre de un dispositivo, como CON, AUX o NUL, en cualquier combinación de mayúsculas y minúsculas y sea cual sea la extensión que siga, como aux/x.yaml, o una parte que termina en un punto o un espacio, como report.. En Windows, aggrega se niega a desempaquetar una entrada así, de modo que un workspace de Windows no puede usar la versión. La advertencia se escribe en la salida de error estándar en todas las plataformas, una línea por entrada, antes del propio resumen de la publicación; el nombre de archivo del propio documento de la entidad se evalúa junto con los archivos que nombra, y una entidad que no nombra nada se publica solo como su documento y nunca recibe advertencias. No rechaza nada: el push continúa o se rechaza exactamente como lo haría sin ella, y --dry-run advierte del mismo modo. A published archive carries an entry Windows cannot use (Un archivo comprimido publicado contiene una entrada que Windows no puede usar) muestra la línea y qué hacer al respecto.
Un source: local escrito como plantilla lleva consigo todo el directorio. Una plantilla como ./charts/{{ .values.flavour }} nombra un directorio solo cuando una Release la rellena, así que ninguna publicación puede saber cuál será. Una entidad así lleva consigo cada archivo de su propio directorio que conservan sus reglas de exclusión registradas —nunca su .aggregaignore, cuyas reglas viajan dentro del lock—, y el push lo indica bajo sus demás datos:
carries: every file in the entity's directory, because its source "./charts/{{ .values.flavour }}" is a template and the directory it names is decided by each Release that uses itLo que no se nombra no viaja, y quien lo descubre es un consumidor. Un archivo del que depende la entidad sin nombrarlo mediante uno de los campos anteriores no está en la publicación, y el build de un consumidor falla indicando la ruta que falta dentro de su ranura de caché, no tu push. Nombra cada archivo que necesita la entidad mediante uno de esos campos.
Cada archivo publicado se nombra en el manifiesto del artefacto, de modo que un cliente OCI genérico como oras lo escribe en un archivo con ese nombre: entity.yaml para una entidad publicada como su documento, entity.tar.gz para una publicada con sus archivos, y, para un Plugin, entity.yaml para la entidad junto a entity.wasm para su ejecutable. El nombre depende del tipo de medio, no del archivo desde el que publicas, así que el mismo contenido publicado desde un archivo renombrado publica el mismo artefacto. Catálogo y registro §6 enumera cada forma publicada y el archivo con el que llega cada una.
Una URL source: remota en una Recipe (una referencia a un chart OCI, una URL de chart o de fragmento HTTPS, un módulo Git) se conserva literalmente en el YAML publicado; no se obtiene ni se incorpora al artefacto. Los consumidores resuelven y fijan las fuentes remotas de forma independiente en el momento de su propio pull. Esto mantiene la distribución de entidades de catálogo y la resolución de artefactos de fuente como aspectos separados.
Un Aggregate se publica como su propio documento único: un subaggregate al que hace referencia en aggregates: no se incluye en el artefacto. Cada subaggregate es un Aggregate publicado por separado que los consumidores resuelven y fijan de forma independiente en el momento del pull, por identidad: el mismo principio de separación de la distribución que se aplica a las fuentes remotas.
Una entidad por directorio
Un archivo comprimido contiene el archivo de la entidad entre los archivos que nombra, así que la entidad tiene que volver a encontrarse al extraerlo. Un consumidor la encuentra por el preámbulo que lleva: el documento en la parte superior del paquete cuyo kind: es un tipo de entidad publicable es la entidad. El archivo en el que está escrita puede llamarse de cualquier forma —recipe.yaml es la convención del catálogo, no un requisito—, y un fragmento de compose, una plantilla de chart o un manifiesto de Kubernetes situado junto a la entidad no se confunde con ella, porque esos declaran otra cosa o ningún tipo. Los documentos de entidad más abajo, dentro de un árbol source/, son contenido que distribuye la entidad y no la entidad en sí, y nunca se tienen en cuenta.
Un push rechaza una entidad que comparte su directorio con otra entidad. Cada tipo tiene un directorio propio excepto Aggregate, Release y Manifest, que la raíz de un workspace contiene uno junto a otro. Para cualquier otro tipo, un push comprueba antes de hacer nada más con la entidad —antes del paso de pin, la política de firma y el paquete— que ningún otro documento de entidad esté en el mismo directorio, y en caso contrario lo rechaza, indicando cada entidad que estorba, tanto si se le pidió al push que fijara pins como si no. aggrega pin rechaza el mismo directorio con las mismas palabras; la detención es An entity shares its directory with another entity (Una entidad comparte su directorio con otra entidad). Un documento que no es de ningún tipo de entidad junto a la entidad —un archivo de chart, un fragmento de compose, un README— no estorba, ni tampoco nada de un subdirectorio. Cada documento junto a la entidad se lee solo desde dentro del workspace o, para una entidad que nombras fuera de él, desde dentro del propio directorio de la entidad, de modo que uno que es un enlace que lleva hacia fuera detiene el push indicando el enlace, sin leerlo, como establece el límite del workspace.
La regla es lo que hace que un entity.lock pertenezca a una sola entidad: el nombre de archivo del lock es el mismo para todas las entidades, así que dos entidades escritas en un mismo directorio compartirían el único lock para el que hay espacio. Solo se evalúa cuando se produce algo a partir del directorio, de modo que un directorio que contiene varias entidades sigue cargándose, pasando el lint y compilándose.
El nombre del directorio no se evalúa. Una entidad sola en su directorio se publica en su metadata.version dondequiera que esté ese directorio; <name>/<version>/, la estructura que sigue el catálogo de la biblioteca estándar, es una convención. Un artefacto que otro cliente publicó desde un directorio que contiene dos entidades se lee igualmente de forma segura: un pull de él se detiene indicando ambos documentos en lugar de responder con cualquiera de ellos, según se recoge en errors/fatal-halts.md.
Leer la entidad antes de empaquetarla
Un push lee un Component, una Feature, una Recipe o una FeatureRecipe del mismo modo que los lee un build, y rechaza lo que esa lectura rechaza, por el mismo motivo y con el mismo código corto, antes de que se construya el paquete y antes de contactar con el registro de destino. Así, un documento que no cumple el esquema de su tipo, una ruta que nombra contenido fuera del propio directorio de la entidad y un esquema que un Component o una Feature importa con $import: y que falta o no se puede usar se rechazan en la publicación en lugar de publicarse. Cada uno de ellos es una entidad que el primer build de sus consumidores rechazaría; una ruta que sale del directorio también nombra un archivo que no viajaría con la entidad, porque cada archivo que lleva una publicación se toma del propio directorio de la entidad —consulta A path names content outside the entity’s own directory (Una ruta nombra contenido fuera del directorio propio de la entidad).
Una Recipe o una FeatureRecipe se lee de este modo mientras se comparan sus pins, como describe la sección siguiente, de modo que la lectura se produce tanto si se le pide al push que fije pins como si no, y tanto si la entidad tiene algo que fijar como si no. Cada uno de los cuatro tipos también se lee de este modo inmediatamente antes de construir su paquete, porque es esa lectura la que indica qué archivos nombra. Un Aggregate y una biblioteca no nombran ningún archivo y no se leen de este modo. Un Plugin tampoco nombra ningún archivo, y se lee con respecto al esquema de su tipo antes que su .wasm, como describe Publicar un Plugin.
Publicar un Plugin
Un Plugin se publica junto con su .wasm, indicado con --plugin, y un push evalúa ambos antes de que se publique ningún byte o se contacte con el registro. --dry-run los evalúa exactamente igual que una publicación.
Primero se lee la entidad con respecto al esquema de su tipo, del mismo modo que la lee una carga del catálogo, antes de leer el .wasm. Así, un metadata.version que no es una versión semántica —un simple commit como 415148e— se rechaza según la condición propia del esquema, indicando el campo, y lo mismo ocurre con cualquier otra desviación del esquema, como un spec.abiVersion ausente. Lo que cuenta aquí como versión semántica es el patrón propio del esquema para metadata.version; el push no añade ninguna regla propia.
Después se carga el .wasm y se contrasta con la entidad. Lo que declara ofrecer debe coincidir con lo que afirma la entidad, el conjunto de comandos y las funciones de host que registra la entidad deben corresponderse con él, y la versión que declara de su propia compilación debe ser igual a metadata.version —consulta A Plugin entity’s recorded version does not match the plugin (La versión registrada de una entidad Plugin no coincide con el plugin).
Se rechaza un .wasm compilado a partir de un árbol de trabajo con cambios sin confirmar. Una compilación así lleva la marca -dirty al final de la versión que declara: 1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty. Es una versión semántica válida, pero nombra un commit que no contiene lo que se compiló, de modo que nadie podría volver a compilar lo publicado a partir de la versión con la que se publicó. El push la rechaza, indicando la versión y la solución: compila el plugin a partir de un checkout limpio del commit que indica la etiqueta de la versión publicada, para que declare la propia versión publicada —y, para publicar el cambio, confírmalo con el metadata.version de la entidad establecido en la nueva versión y etiqueta primero ese commit—, en lugar de copiar en la entidad la versión que declara una recompilación. Una versión de desarrollo compilada a partir de un commit, como 1.0.0-3-g1a2b3c4, y una versión preliminar como 1.0.0-rc.1 se publican ambas. El rechazo es A plugin was built from a working tree with uncommitted changes (Un plugin se compiló a partir de un árbol de trabajo con cambios sin confirmar).
Fijar antes de publicar
Una Recipe o FeatureRecipe lleva los pins de las entradas que lee —un source: remoto escrito por completo, un archivo que importa una entrada de artifacts, los archivos de un source: junto a ella— en el entity.lock que tiene al lado, y un push publica ese archivo con la entidad. Fijar es un paso que ejecutas antes de publicar, aggrega pin, y luego confirmas el lock que escribe.
Un push rechaza una entidad cuyo lock no registra esos pins. Antes de construir el bundle, un push determina qué registraría el paso de fijación para la entidad y lo compara con el entity.lock que tiene al lado. Donde falta un pin, o el lock contiene uno con el que una entrada ya no coincide, el push se detiene antes de construir ningún archivo comprimido o de contactar ningún registry. El rechazo nombra la entidad y cada una de esas entradas —cada una un remote source, un imported file o un local source file— y qué ejecutar: aggrega pin sobre la entidad, --pin-sources en el push que acabas de ejecutar, o pin_sources_at_push para cada push del workspace. Es el mismo rechazo que un pull emite sobre el mismo lock, An entity reads an input the lock beside it records no pin for (Una entidad lee una entrada para la que el lock que tiene al lado no registra ningún pin), con los remedios propios de un push. Así, una Recipe o FeatureRecipe que publica un push lleva, dentro de su bundle, un lock que registra cada pin que el paso habría registrado en el momento en que se publicó.
Dos tipos de entidad no tienen nada que fijar y se publican sin cambios: una entidad que no lee ninguna fuente remota, no importa ningún archivo y no nombra ninguna fuente local, y una Recipe cuyas coordenadas de fuente remota se rellenan a partir de una plantilla. Esa fuente solo nombra un artefacto cuando una Release rellena la plantilla, por lo que su pin pertenece al lockfile de cada Release, y un push no pide uno junto a la entidad. Un Component, una Feature, una biblioteca, un Aggregate o un Plugin no lee nada de lo que registra el lock y nunca se rechaza aquí.
Comparar el pin de una fuente remota implica descargar la fuente, como hace aggrega pin, porque un pin que ya no coincide solo es visible frente a lo que la fuente sirve ahora. Por eso, un push sobre una entidad con una fuente así llega al host de la fuente antes de llegar al registry. La comparación lee una Recipe o FeatureRecipe como lo hace el paso de fijación, a través del catálogo, de modo que una que el catálogo se niega a leer —por ejemplo, un documento que no supera el esquema de su tipo— se rechaza aquí con el motivo propio del catálogo.
Donde no se encontró ningún workspace y no se indicó ninguno, un push que descargaría una fuente remota para la comparación se rechaza antes de descargarla, igual que aggrega pin. La comparación descarga cada fuente remota que la entidad escribe por completo en la caché de artefactos, exactamente como hace el paso de fijación, y una caché escrita en una carpeta desde la que no se encontró ningún workspace convertiría esa carpeta en un workspace. Así, cuando nada nombra una raíz y nada ancla una —desde la carpeta en la que ejecutas el push o, para una entidad indicada con una ruta absoluta, desde la propia carpeta de la entidad—, un push de una Recipe o FeatureRecipe con una fuente así se detiene antes de descargar la fuente, incluidos un dry run y --pin-sources, y nombra la fuente, la carpeta y las dos soluciones: indica tu workspace con --workspace-root o AGGREGA_WORKSPACE_ROOT, o dale a esa carpeta un .aggrega-config.yaml que contenga un bloque workspace:. La comparación no descarga nada para los dos tipos de entidad anteriores, ni para una cuya fuente es local, de modo que cada una de ellas se compara con su lock y se publica allí como en cualquier otro lugar; y cualquier otro tipo no está sujeto a un lock y no se rechaza por esto. Configuración enumera los demás comandos para los que esto se aplica.
aggrega push --pin-sources ejecuta ese mismo paso por ti, primero. El paso se ejecuta antes de construir el bundle, de modo que el lock que escribe está en el artefacto publicado y el digest publicado lo cubre; y se ejecuta antes que cualquier otro rechazo que juzgue la entidad, de modo que lo que se juzga es la entidad ya fijada. Solo la regla de directorio anterior va antes, porque el paso escribe el único lock que contiene el directorio. Escribe los mismos bytes que escribe aggrega pin, así que el rechazo anterior nunca se activa en esa ejecución: el lock que el paso acaba de escribir registra exactamente aquello con lo que compararía el rechazo. La clave del workspace pin_sources_at_push convierte esto en el comportamiento predeterminado de cada push, y --pin-sources=false omite el paso en una ejecución, lo que devuelve el rechazo. El paso escribe junto a la entidad, lo que requiere una ubicación con permisos de escritura, y un push siempre la tiene, ya que publica el documento que indicas.
--dry-run responde como lo haría la publicación. Sin --pin-sources rechaza una entidad sin fijar exactamente como lo hace la publicación, de modo que un dry run que informa de un bundle es uno que este rechazo dejaría pasar. Con --pin-sources el paso fija en modo dry run: imprime el lock que escribiría y no escribe nada, y los datos del bundle que siguen describen el directorio tal como está, sin ese lock; así, el digest es el de una publicación sin él y, donde el lock sería nuevo, también lo son el tamaño y, para una entidad que no nombra nada más, el media type. El rechazo no se activa, porque la publicación habría fijado primero.
Buena práctica: un cambio en una versión que ya publicaste va en una versión nueva y, después, en un pin. Copia la entidad en un directorio de versión nuevo, haz allí el cambio, fíjala y publica esa. La mitad de esto que el producto impone es la sección siguiente: publicar contenido distinto en una versión ya publicada se rechaza. La otra mitad —no volver a fijar una versión ya publicada después de editarla en tu propio workspace— te corresponde a ti; nada lo rechaza localmente, porque volver a fijar es legítimo para una entidad que no has publicado.
Registry, tag y direccionamiento por contenido
El registry de destino es --registry <ref> cuando se indica; si no, el default_registry del workspace (hub.aggrega.ai de forma predeterminada). El tag es el metadata.version de la entidad, y la ruta del repositorio se deriva de su tipo y su nombre, de modo que el lugar donde acaba una versión publicada no depende del directorio desde el que se publicó.
Un default_registry puede incluir una ruta de repositorio, y una publicación a través de él acaba bajo esa ruta. Con default_registry: ghcr.io/acme, el Component core/api-server en la versión 1.0.0 se publica en ghcr.io/acme/component/core/api-server:1.0.0, el lugar desde el que lo descarga un pull a través del mismo valor predeterminado, de modo que la firma adjuntada aquí es la que encuentra ese pull. --registry nombra un host, y una publicación dirigida por él acaba en ese host sin ruta. Sea cual sea la forma de nombrar el destino, el requisito de firma y la configuración de firma que se aplican son los que se mantienen para su host: una ruta nunca selecciona una política distinta. La forma de escribir una ruta se detalla en cómo se escribe un host de registry.
El manifest nombra el digest de los bytes publicados, y el lockfile registra el digest de lo que contienen. El manifest OCI que escribe un push nombra el digest del documento o archivo comprimido publicado, y aggrega pull rechaza una descarga que no coincide con él, de modo que se detectan los bytes alterados entre la publicación y el pull. El lockfile que escribe un pull registra la entidad con un digest distinto: el digest de su contenido, es decir, la ruta y los bytes de cada archivo, y nada sobre cómo se comprimió el archivo ni qué bits de permisos tenían sus archivos. Es el digest que un pull en el propio workspace del autor registra para la misma entidad en su directorio de catálogo, de modo que un autor y cada consumidor de una publicación registran el mismo valor, y un build en cualquiera de los dos lados rechaza el contenido que ya no coincide con él. Los dos digests responden a preguntas distintas: el del manifest comprueba la descarga, y el del lockfile es la identidad de la entidad.
Publicar sobre una versión existente
Antes de subir ningún byte, aggrega push determina qué contiene ya el registry de destino en la referencia que está a punto de escribir y lo compara con el contenido que tiene delante. Tres resultados:
- Todavía no hay nada publicado allí: el push continúa y publica con normalidad.
- El mismo contenido: no se sube nada, y el comando informa de que la versión ya está publicada, de modo que un push repetido o reintentado no es un error. Lo que un push anterior dejó sin adjuntar —la firma o la fecha de publicación— se adjunta ahora, como se describe en Completar una publicación que un push anterior dejó parcial.
- Contenido distinto: el push se detiene, nombrando el digest ya publicado y el que habría escrito. Ningún flag lo fuerza.
Por lo tanto, una versión ya publicada sigue designando los bytes publicados bajo ella. El contenido que ha cambiado se publica bajo un nuevo metadata.version; aggrega lint --pre-publish responde a la siguiente pregunta —cuánto debe avanzar esa versión— clasificando el cambio frente a la versión publicada anteriormente.
--dry-run imprime el digest que escribiría un push, junto a la referencia en la que lo escribiría:
aggrega push (dry-run): <reference>:<tag> (<digest>)Es el digest que el propio push compara con lo que ya está publicado, calculado de la misma manera solo a partir del contenido, e imprimirlo no contacta con ningún registry. Así, el contenido que tienes delante se puede contrastar con el digest con el que se publicó una versión antes de hacer ningún push: donde difieran en una versión publicada, el push se rechazaría. Con --pin-sources, es el digest del directorio tal como está, como se describe en Fijar antes de publicar.
Completar una publicación que un push anterior dejó parcial
Un push escribe primero el contenido y adjunta la firma y la fecha de publicación después, de modo que un push que falla en uno de esos adjuntos —tras sus reintentos— deja el contenido publicado sin él y termina con un código distinto de cero nombrando lo que no pudo adjuntar. Ejecutar de nuevo el mismo push completa esa publicación. Encuentra el contenido ya publicado, imprime la línea Already published:, no sube nada y adjunta lo que todavía le falta a la versión, cada cosa en la línea que una primera publicación imprime para ella:
- La firma, donde este push firma. Se adjunta cuando la versión no lleva ninguna firma que cuente como la de esta publicación. Donde tu configuración fija una política de confianza para el host del destino —una
public_keyotrusted_identities, o parahub.aggrega.aila línea base integrada—, una firma cuenta cuando se verifica bajo esa política, de modo que una firma que la política no admite nunca se toma por la propia de la publicación. Donde la política no fija ninguna de las dos, ninguna firma puede verificarse frente a ella, de modo que cuenta cualquier firma que lleve la versión y el push solo firma una versión que no lleva ninguna; juzgar por verificación en ese caso adjuntaría otra firma en cada ejecución. - La fecha de publicación, donde la regla de las fechas exige una —leída de la firma recién adjuntada, o de la que ya se contó— y la versión no lleva ningún referrer published-at. Un push que no firma debe una fecha como una publicación sin firmar, independientemente de las firmas que se adjuntaran a la versión después. La fecha que indica es el reloj de este push: el momento en que se completó la publicación, que es posterior al momento en que el contenido llegó por primera vez, ya que nada de lo que sirve el registry registra ese momento.
A una publicación ya completa no se le adjunta nada, por muchas veces que se repita el push. Antes de adjuntar nada, el push lee qué firmas y fechas lleva la versión y crea cualquier firma que deba. Una pregunta que no puede responder —un listado o una firma que no puede leer, o una firma que no puede juzgar porque no se puede obtener la raíz de confianza— y una firma que no puede crear terminan cada una con un código distinto de cero sin adjuntar nada, en lugar de interpretarse como que la versión no lleva ninguna.
Cuando el registro hace fallar una escritura
Un push escribe en el registry por pasos: el contenido —para un Plugin, la entidad y su .wasm—, después el manifest que lo nombra, después el tag de versión y después la firma y la fecha de publicación junto a él. Cada paso que escribe se reintenta cuando falla de una manera en la que un intento posterior puede tener éxito: el registry responde con un error de servidor (cualquier estado 5xx, salvo un 503 que lleve Retry-After) o 408 Request Timeout, o la conexión agota el tiempo de espera, se restablece o termina a mitad de una respuesta. Un paso se intenta como máximo tres veces, esperando medio segundo antes del segundo intento y un segundo antes del tercero.
A un registry que pide ir más despacio se le espera, y no consume ninguno de esos intentos. Ante un 429 Too Many Requests, o un 503 que lleve Retry-After, cada solicitud a ese registry —tanto una lectura como una escritura— espera lo que el registry pidió y luego vuelve a enviarse, y un paso cuyo contenido fue rechazado empieza de nuevo como una subida nueva, sin un número fijo de intentos, hasta que el registry no ha respondido otra cosa que «más despacio» durante cinco minutos. Un registro que pide ir más despacio describe la espera y el rechazo que la termina.
Cada intento es una nueva subida de los mismos bytes, nunca un reenvío de la solicitud que falló. Un registry que ya ha recibido el cuerpo de una subida puede rechazar la misma solicitud una segunda vez, y lo que acepta es una nueva subida. El contenido que el registry ya tiene cuenta como subido, y un paso reintentado escribe lo que habría escrito el primer intento, de modo que un intento que llegó pero cuya respuesta se perdió no escribe nada dos veces: el manifest conserva su digest, y la versión lleva una sola firma y una sola fecha de publicación.
Cualquier otro fallo termina el paso de inmediato: una credencial rechazada (401, 403 o ninguna credencial almacenada para el registry), cualquier otra respuesta del registry, un registry al que no se puede llegar en absoluto, o un push que interrumpes. Un paso que sigue fallando tras su último intento hace fallar el comando, y el error nombra el paso: el contenido, el manifest, el tag, la firma o la fecha de publicación. Lo que publicaron los pasos anteriores sigue publicado; Firma y La fecha de publicación explican lo que eso significa para la versión.
Para esos fallos solo se reintentan las escrituras. La lectura de lo que el registry ya contiene en la versión, antes de subir nada, no, aunque, como toda solicitud, espera lo que indique un registry que pide ir más despacio.
Firma
aggrega push puede firmar el artefacto mientras lo publica y adjuntar la firma como referrer OCI: un bundle de Sigstore (compatible con cosign) sobre el digest inmutable del manifest del artefacto. La firma es un manifest hermano, de modo que firmar nunca vuelve a subir ni modifica los bytes publicados. El referrer llama a su bundle signature.json, de modo que un cliente OCI genérico que descarga el referrer por su digest escribe el bundle en ese archivo.
La firma es sign-before-push: el digest del manifest se conoce antes de publicar, así que aggrega push construye el firmante y firma el digest antes de que ningún byte llegue al registry. Si el firmante no se puede construir o la firma falla, el push se rechaza antes de subir nada; no se publica nada, de modo que una firma fallida nunca deja contenido sin firmar en el registry. Antes de rechazar, una llamada de firma que falló de forma transitoria —cualquier fallo por el que se reintenta una escritura en el registry, o la autoridad de certificación keyless informando de que no pudo procesar el token de identidad— se reintenta, hasta tres intentos con las mismas esperas. Dentro de una llamada de firma keyless, una solicitud a la que la autoridad de certificación, el registro de transparencia o la autoridad de sellado de tiempo responde con 429 Too Many Requests o con un error del servidor se envía primero de nuevo a ese servicio, como describe aggrega sign.
La firma se adjunta después de que llegue el contenido, así que un adjunto fallido sí deja el contenido publicado sin ella. El adjunto es una escritura, que se reintenta como se describe en Cuando el registry hace fallar una escritura. Si sigue fallando, el comando termina con un código distinto de cero nombrando la firma que no pudo adjuntar, y un consumidor cuyo registry exige firmas rechaza la versión hasta que se adjunte una firma. Ejecutar de nuevo el mismo push la adjunta, como se describe en Completar una publicación que un push anterior dejó parcial; aggrega sign adjunta una a la versión publicada por referencia.
Una publicación exige una firma cuando el bloque signing propio del registry de destino establece required: true, o cuando lo hace el bloque signing de nivel superior para todos los registries, cada uno limitado a los tipos que enumera su kinds, cuando enumera alguno. Una publicación así firma de forma predeterminada, y --sign solicita la firma de forma explícita. No existe ningún flag para hacer push de contenido sin firmar donde se exige una firma: ese push siempre se detiene.
Dos modos de firma:
- Keyless (predeterminado): una clave efímera vinculada a una identidad OIDC mediante un certificado Fulcio de corta duración, registrada en el registro de transparencia Rekor. Fulcio y Rekor usan de forma predeterminada las instancias públicas de Sigstore (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). La marca de tiempo de confianza keyless procede de la inclusión en el registro de transparencia de Rekor; una autoridad de marcas de tiempo RFC3161 independiente es opcional: indica--timestamp-urlcon un endpoint completo para habilitar una. En un terminal interactivo, la firma keyless no necesita flags: la CLI abre un navegador para obtener un token de identidad OIDC de corta duración. En GitHub Actions tampoco necesita ninguno: la CLI genera automáticamente el token OIDC del workflow a partir del endpoint ambiental del runner. Para otros usos no interactivos / CI, exportaAGGREGA_IDENTITY_TOKEN(oSIGSTORE_ID_TOKEN), o pasa--identity-token; sin token proporcionado, sin endpoint ambiental y sin terminal, el push se rechaza. Consulta environment-variables.md para ver el modelo de tokens en CI. - Keyed (
--key): una clave ECDSA P-256 guardada sin conexión (PEM compatible con cosign), la vía de escape para entornos sin proveedor de identidad OIDC. No se contacta con ningún proveedor de identidad, autoridad de certificación ni registro de transparencia.
Las URL de los servicios keyless y la ruta de la clave keyed también se pueden establecer en .aggrega-config.yaml bajo un bloque signing: (global y por registry); un flag sobrescribe la configuración, y la configuración sobrescribe el valor público predeterminado. El token de identidad OIDC nunca es un campo de configuración (es un secreto de corta duración), y la clave privada nunca va inline en la configuración: solo una ruta a ella.
La fecha de publicación
La hora de creación del manifest está fijada, de modo que el digest de un manifest depende solo de lo que se publica y nunca de cuándo. La fecha en que se publicó una versión viaja, en cambio, junto a ella, y su procedencia depende de la firma:
- Una firma keyless ya la lleva. Su entrada en el registro de transparencia registra cuándo el registro integró la firma, y la promesa firmada del registro da fe de ese momento.
aggrega pushno escribe nada más. - Una firma keyed, o la ausencia de firma, no lleva ninguna hora. Así que, después de que lleguen la entidad y cualquier firma,
aggrega pushadjunta al manifest un pequeño referrer published-at —llamadopublished-at.jsonpara un cliente OCI genérico— que contiene una marca de tiempo RFC 3339 en UTC con precisión de segundos, leída del propio reloj de la máquina que publica. No está firmado: es la declaración del publicador, y un lector la registra como tal. La líneaPublication date attached:lo indica.
Como una firma, el referrer published-at es un manifest hermano que apunta al publicado, de modo que no mueve ningún digest ni cambia ningún tag, y la comprobación al publicar sobre una versión existente no se ve afectada. Un push repetido del mismo contenido adjunta una fecha solo a una versión que no lleva ninguna, indicando su propio reloj: consulta Completar una publicación que un push anterior dejó parcial. La fecha se lee del reloj una sola vez, antes del primer intento de adjuntarla, de modo que un adjunto reintentado —consulta Cuando el registry hace fallar una escritura— indica la misma fecha. Un push que publicó su contenido pero no pudo adjuntar la fecha tras esos intentos termina con un código distinto de cero y nombra lo que no se adjuntó. aggrega registry update registra la fecha de cada versión junto con cuál de las dos fuentes la proporcionó.
Sin conexión
Publicar es un viaje de ida y vuelta por la red y no tiene ninguna forma que no lo sea, así que en modo sin conexión —la clave de nivel superior offline en un archivo de configuración, AGGREGA_OFFLINE o --offline— aggrega push rechaza antes de leer tu entidad. El rechazo nombra cuál de esas tres fuentes estableció el modo, que es lo que necesita un lector cuando fue la configuración confirmada de un proyecto la que lo activó y no algo que escribió.
--dry-run es la excepción, y lo es por lo que hace: calcula el bundle, imprime la referencia que publicaría y el digest que produciría esa publicación, y nunca contacta con el registry. Eso lo convierte en la forma de publicar segura sin conexión, en lugar de un conflicto con el modo, y sigue funcionando bajo él, con una salvedad. Para una Recipe o FeatureRecipe cuyo source: remoto está escrito por completo, esa fuente se descarga para comparar su pin, y en modo sin conexión esa descarga se rechaza con su propio mensaje, de modo que un dry run sobre una entidad así se detiene ahí en lugar de informar de un bundle que no puede garantizar.
Para publicar en una ejecución desde un workspace cuya configuración está sin conexión, pasa --offline=false.
Variables de entorno
Los datos de firma y el registry de destino se pueden proporcionar mediante el entorno, sobrescribiendo .aggrega-config.yaml, mientras que un flag sigue prevaleciendo:
AGGREGA_IDENTITY_TOKEN: el token de identidad OIDC keyless (el equivalente en el entorno de--identity-token).SIGSTORE_ID_TOKENse acepta como alias de interoperabilidad del ecosistema sigstore, con menor prioridad queAGGREGA_IDENTITY_TOKENy el endpoint ambiental de GitHub Actions. El token nunca es un campo de configuración.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL: las URL de los servicios keyless.AGGREGA_SIGNING_KEY_PATH: una ruta que apunta a un PEM de clave keyed (nunca el material de la clave).AGGREGA_DEFAULT_REGISTRY: el registry de destino cuando se omite--registry.
La precedencia es flag > entorno > configuración > valor predeterminado. Consulta environment-variables.md para ver la lista completa y el modelo de precedencia.
Autenticación
aggrega push lee las credenciales de registry igual que aggrega pull: de la configuración de credenciales de Docker y de los credential helpers que esta nombra. Ejecuta aggrega login <registry>, que no necesita ninguna otra herramienta, o docker login <registry> antes de hacer push a un registry privado. Consulta aggrega-pull.md para ver dónde se lee esa configuración.
Véase también
- ./aggrega-sign.md: firma a posteriori un artefacto ya publicado (el equivalente posterior a la publicación de
--sign). - ./aggrega-lint.md: el control de publicación (
--pre-publish) que debería preceder a un push. - ./aggrega-pull.md: el lado consumidor, que resuelve y fija lo que publica
push. - ./aggrega-serve.md: el daemon ofrece esta misma publicación en
aggrega/publishEntity, de modo que un editor puede ejecutarla sin salir de la sesión; solo se ejecuta cuando una solicitud la nombra, y responde con la referencia, el digest publicado —en un dry run, el digest que imprime--dry-run—, hasta dónde llegó la llamada y las entradas sobre las que advierte este comando, comowindowsUnusableEntries. - ./aggrega-mcp.md: la misma capacidad como la herramienta
publish-entity, que un asistente puede llamar y que responde con esas entradas comowindows_unusable_entries. Lee lo que dice esa página sobre permitirla antes de hacerlo. - ../../architecture/13-catalog-and-registry.md: el modelo de catálogo, registry y mediatypes OCI.
Sinopsis
aggrega push <entity-path> [flags]Descripción
Publish a single catalog entity to an OCI registry, where other workspacesresolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to<registry>/<kind>/<metadata.name>:<metadata.version>, the repository pathlowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Pluginits metadata.pluginType, as a segment between <kind> and <metadata.name>. Thetag is the entity's own metadata.version. Run "aggrega push --list-kinds" forthe kinds this binary publishes, one per line and nothing else, so a script canread it directly. Release and Manifest are deployment-side inputs rather thancatalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: anentity of any other kind is refused when another entity sits in its directory,before anything is pinned or bundled, and the refusal names the entity in the way.The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads itbefore it is bundled, and one that read refuses is refused here for the samereason: a document that fails its kind's schema, a path naming content outsidethe entity's own directory, which would not travel with the entity, or a schemaa Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so ametadata.version that is not a semantic version is refused. Its .wasm must thenagree with the entity on what the plugin offers and on its version, and a .wasmwhose version says it was built from a working tree with uncommitted changes —the -dirty mark a build adds — is refused. A version disagreement and a buildfrom uncommitted changes are both cleared by building the plugin from a cleancheckout of the commit its release tag names, never by copying the version itreports into the entity. A development version such as 1.0.0-3-g1a2b3c4, builtfrom a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself namesbeside it — a Recipe's or FeatureRecipe's local source, each file an $import:names, the entity.lock beside it, and each schema file a Component or Featureimports — and nothing else in its directory. An entity that names nothingpublishes as its document, unchanged; one that names a file publishes as agzipped archive of the document and those files. A directory it names travelswith every file under it that the ignore rules recorded in its entity.lock keep:the rules the plugin serving its capability declared, and the author's own.aggregaignore beside it, composed when the entity was pinned. A symbolic linkamong those files is refused rather than followed. A local source written as atemplate names no one directory until a Release fills it in, so an entity withone carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windowscannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or apart ending in a full stop or a space. On Windows, aggrega refuses to unpacksuch a file, so a Windows workspace cannot use the version. The warning iswritten to standard error on every platform, one line per file, the entitydocument's own file name judged with the rest, and it refuses nothing: the push,or its dry run, goes ahead or stops exactly as it would without it. An entitythat names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the executebit included — in the checkout it is published from. The OCI manifest names thedigest of the published bytes, so "aggrega pull" refuses a download that doesnot match it. The lockfile a pull writes records the entity by the digest of itscontent — each file's path and its bytes — which is the digest a pull in theauthor's own workspace records for the same entity in its catalog directory, soa build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is madeover the manifest digest before any bytes reach the registry, so a failedsigning refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what ispublished and never on when. Push states when it published beside the manifestinstead, as a small published-at attachment carrying this machine's clock, inUTC to the second — unless the signature it attached already carries a time atransparency log attests, as a keyless signature does. So a keyed or unsignedpublication writes one, and a keyless one does not. The attachment moves nodigest and changes no tag. "aggrega registry update" records the date, withwhich of the two it came from.
Push refuses to replace content already published at the same version:publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lockbeside it, and pinning them is a step you run before publishing: aggrega pin.A push that does not run that step refuses an entity whose entity.lock ismissing a pin, or holds one an input no longer matches, and names the step.Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, tohave push run that same step first, so the lock it writes is part of what ispublished; --pin-sources=false skips it for one run.Flags
| Flag | Predeterminado | Descripción |
|---|---|---|
--dry-run | false | Calcula el bundle e imprime la |
--entity | — | Ruta al YAML de la entidad que se va a publicar (también se puede pasar como argumento posicional) |
--fulcio-url | — | URL de la autoridad de certificación Fulcio para la firma sin clave. Si se omite, se usa la instancia pública de Fulcio. |
--identity-token | — | Token de identidad OIDC para la firma sin clave. Opcional en un terminal interactivo (un flujo en el navegador obtiene uno) y en GitHub Actions (el token OIDC del workflow se emite automáticamente); obligatorio para otros usos no interactivos/CI, donde en su lugar se puede exportar como AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN. |
--key | — | Ruta a un PEM de clave privada ECDSA P-256 en tu poder para la firma con clave sin conexión. Si se omite, se usa la firma sin clave. |
--list-kinds | false | Enumera cada tipo de entidad que se puede publicar y luego sale sin publicar nada. La salida es legible por máquina y su forma es estable: un tipo por línea, en orden, sin nada más. |
--pin-sources | false | Ejecuta el paso de fijación del autor de la entidad sobre la entidad antes de empaquetarla, de modo que el entity.lock que el paso escribe junto a ella forma parte de lo que se publica, en lugar de rechazar una entidad cuyo lock no registra sus pins. El mismo paso que aggrega pin, que escribe los mismos bytes. Escribe junto a la entidad, por lo que solo se ejecuta donde la entidad tiene una ubicación con permisos de escritura: un documento en un directorio desde el que se leyó, que un push siempre tiene, ya que publica el documento de entidad que indicas. Sobrescribe pin_sources_at_push del workspace en ambos sentidos: —pin-sources fija en esta ejecución y —pin-sources=false no, diga lo que diga la configuración |
--plugin | — | Ruta al artefacto .wasm local de una entidad Plugin. Obligatorio al publicar un Plugin: la publicación sube el artefacto .wasm, calcula su digest de contenido y sube la entidad. |
--registry | — | Host del registro de destino (anula el default_registry del workspace) |
--rekor-url | — | URL del registro de transparencia Rekor para la firma sin clave. Si se omite, se usa la instancia pública de Rekor. |
--sign | false | Firma el artefacto publicado y adjunta la firma como referrer OCI. Si se omite, la firma sigue la política del registry de destino. |
--timestamp-url | — | URL opcional de la autoridad de sellado de tiempo RFC3161 para la firma sin clave. |