Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

aggrega deprecate

Adjuntar un marcador de obsolescencia firmado a un artefacto ya publicado

Sinopsis

aggrega deprecate <reference> [flags]

Descripción

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.

Flags

FlagPredeterminadoDescripción
--from—Archivo de lote (YAML, o JSON como subconjunto) cuya lista de nivel superior adjunta un marcador por entrada. Cada entrada contiene reference, severity y reason, además de replacement y message opcionales. Mutuamente excluyente con una referencia posicional y con —severity, —reason, —replacement y —message.
--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.
--message—Mensaje opcional que se conserva para auditoría y para el diagnóstico registrado en tiempo de compilación; si no se establece, toma el valor de —reason. Se rechaza junto a —from, cuyas entradas llevan el suyo propio.
--reason—Motivo legible por personas de la obsolescencia — por qué está obsoleto y qué hacer en su lugar. Obligatorio con una referencia posicional salvo que lo proporcione una solicitud interactiva; se rechaza junto a —from, cuyas entradas llevan el suyo propio.
--rekor-url—URL del registro de transparencia Rekor para la firma sin clave. Si se omite, se usa la instancia pública de Rekor.
--replacement—Referencia opcional al artefacto que sustituye al obsoleto. Se rechaza junto a —from, cuyas entradas llevan la suya propia.
--severity—Severidad de la obsolescencia: una de warning, error, retracted. Obligatoria con una referencia posicional salvo que la proporcione una solicitud interactiva; se rechaza junto a —from, cuyas entradas llevan la suya propia.
--timestamp-url—URL opcional de la autoridad de sellado de tiempo RFC3161 para la firma sin clave.

De dónde proceden los endpoints de firma

Las URL de Fulcio y Rekor de la firma sin clave y la ruta de la clave de la firma con clave también pueden proceder del bloque signing: de .aggrega-config.yaml (global y por registro, donde un valor establecido para el registro del artefacto tiene prioridad sobre el global, campo por campo); un flag anula la configuración, y la configuración anula el valor predeterminado public-good. Así que las instancias public-good indicadas en la tabla de flags solo se usan cuando ni un flag ni la configuración de tu workspace indican un endpoint. El marcador se firma exactamente como aggrega sign firma un artefacto.

Cuando el registro hace fallar una escritura

Marcar un artefacto como obsoleto escribe dos veces en el registro: el marcador, adjuntado como referrer del artefacto, y después la firma del marcador, adjuntada como referrer del marcador. Cada escritura 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 lista 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 carga de los mismos bytes en lugar de un reenvío de la solicitud que falló. La marca de tiempo del marcador se estampa una sola vez, antes del primer intento, de modo que una escritura reintentada deja un marcador y una firma, no dos.

La firma del marcador, entre las dos escrituras, no se reintenta en su conjunto; dentro de una 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 de nuevo a ese servicio, como describe aggrega sign. Una escritura que sigue fallando tras su último intento, o una firma que falla, detiene el comando y nombra el paso; un marcador ya adjuntado para entonces permanece adjuntado sin su firma. Con --from, las entradas adjuntadas antes de la que falló permanecen adjuntadas.

Un archivo de lote lleva el contenido de cada marcador

Con --from, la severidad, el motivo, la sustitución y el mensaje de cada marcador proceden de su propia entrada en el archivo de lote. Por eso, un --severity, --reason, --replacement o --message pasado junto a --from se rechaza en lugar de ignorarse: el comando nombra cada uno de los que se pasaron y se detiene antes de leer el archivo de lote, de modo que no se adjunta ningún marcador. Pon el contenido en las entradas del archivo, o marca como obsoleta una sola referencia con sus flags de contenido.

Un lote se firma con una sola credencial

Con --from, cada marcador del archivo de lote se firma con la misma credencial: una única clave en tu poder, o una única identidad sin clave solicitada una vez para todo el archivo. Cuál necesita una entrada lo decide la configuración del registro de su referencia — un signing.key_path que se aplica a ese registro selecciona la clave que nombra, y donde no se aplica ninguno el marcador se firma sin clave. Cuando las entradas necesitarían credenciales distintas — la configuración nombra una clave para un registro y ninguna para otro, o dos claves distintas —, no se adjunta ningún marcador y el comando nombra los registros de cada lado. Lo hace antes de que se solicite ninguna identidad y antes de que se lea ningún registro.

Divide el archivo en un lote por credencial, o pasa una sola clave con --key, que se aplica a todas las entradas diga lo que diga la configuración para cada registro. El mensaje se describe en References signed together need different signing credentials (Las referencias firmadas juntas necesitan credenciales de firma distintas).

El firmante de cada entrada también se prepara antes de adjuntar el primer marcador, de modo que una clave que no se puede leer, o un token de identidad proporcionado que no contiene ningún sujeto utilizable, detiene el lote sin que se haya adjuntado nada.

Qué hace cada severidad

Las tres severidades forman un conjunto ordenado — warning, luego error, luego retracted — y se dividen en dos niveles que difieren en cuándo actúan.

warning y error son niveles informativos. Un marcador con cualquiera de esas severidades nunca cambia la versión a la que se resuelve una referencia. Se registra cuando ejecutas aggrega pull, y toda superficie que lee el lockfile lo notifica.

Cada una de esas superficies notifica todas las referencias obsoletas que fija el lockfile, sea cual sea la severidad, nombrando la referencia, su severidad, su mensaje y cuándo se observó el registro:

SuperficieQué hace con un marcador registrado
aggrega buildLo notifica y se detiene si configuraste una detención en esa severidad.
aggrega validate --releaseLo notifica. El veredicto no cambia.
aggrega lint --releaseLo notifica. El veredicto no cambia.
aggrega serveLo publica en tu editor como advertencia mientras el Aggregate está abierto. Un marcador nombra una referencia o un plugin en lugar de un documento de tu espacio de trabajo, así que permanece en el Aggregate; solo los errores de mapeo propios de un Manifest se muestran en el Manifest.
La herramienta build nativa para IALo notifica y se niega si configuraste una detención en esa severidad.
Las herramientas describe y validate nativas para IALo notifican junto con su propia salida.

Que un marcador también detenga una compilación es una opción aparte: build.halt_on_deprecated_severity no está establecida de forma predeterminada, por lo que nada se detiene, y establecerla en una severidad detiene en esa severidad y superiores. Rige la compilación — aggrega build y la herramienta de compilación nativa para IA, que es la misma operación — y nada más: las superficies que notifican nombran el marcador y continúan en cualquier caso. Subir el umbral nunca reduce lo que se te comunica, en ninguna superficie — sigues recibiendo el aviso de todo lo que está por debajo y de todo lo que la detención no cubre.

Algunos plugins se registran en otro lugar, y sus marcadores proceden de allí. Un anexo plugins.linter, y un anexo plugins.governance con un rol ir-verdict o render-verdict, no dan forma a ninguna parte de la salida renderizada, por lo que se fijan en plugins-trust.yaml junto al lockfile en lugar de en el propio lockfile. Cada registro de ese archivo contiene el marcador descubierto para el plugin que nombra, junto con su identidad, y aggrega pull registra uno del mismo modo en que registra un marcador en una fila del lockfile.

aggrega build, aggrega lint --release y aggrega validate --release leen ambos registros, por lo que un plugin obsoleto se nombra allí igual que una referencia obsoleta, y build.halt_on_deprecated_severity rige ambos por igual. Conviene conocer dos diferencias. El aviso para un plugin así no dice cuándo se observó el registro — ese archivo no contiene ninguna marca de tiempo, que es lo que hace que se reproduzca byte a byte —, así que nombra en su lugar de dónde procede el dato y el comando que lo actualiza. Y una entrada de ese archivo nunca se reescribe con un pull normal: un marcador recién publicado se añade al registro que ya tiene el plugin, mientras que la identidad a la que está sujeto se mantiene hasta que pidas cambiarla con aggrega pull --upgrade.

retracted es el nivel de retirada, y además actúa antes. Una versión registrada como retirada se excluye de la consideración cuando aggrega pull elige una versión para una referencia que no nombraba ninguna. Si otra versión publicada satisface la referencia, se toma esa versión y el pull lo indica, nombrando la versión que omitió, el motivo registrado contra ella y la versión que tomó en su lugar. Si no queda ninguna versión publicada que satisfaga la referencia, el pull se detiene e indica que todas las candidatas se han retirado — no notifica la entidad como inexistente, y nunca recurre a otra en silencio.

Nombrar una versión explícitamente anula la retirada

Una referencia que nombra una versión exacta siempre se resuelve a esa versión, se haya retirado o no. Nombrar la versión es la anulación, por lo que no existe ninguna opción aparte para desactivar la exclusión — y una versión fijada por un aggrega pull anterior sigue resolviéndose exactamente por el mismo motivo.

El pull lo dice abiertamente cuando la versión que nombraste se ha retirado, de modo que la compilación que ya se había comprometido con ella sigue funcionando mientras puedes ver por qué tal vez quieras cambiar.

Los registros de retirada son una instantánea, no una respuesta en tiempo real

Un artefacto publicado es inmutable, pero una retirada no: una versión puede retirarse después de la última vez que lo comprobaste. La exclusión lee lo que tu workspace registró la última vez que construyó su índice local del registro, de modo que te protege de seleccionar una versión que se sabe retirada. No puede decirte que una versión no esté retirada en este momento.

Cada notificación de un marcador registrado anteriormente indica cuándo se observó ese registro, de modo que un registro antiguo se distingue de uno reciente, y cada una nombra el comando que lo actualiza. Se conservan dos registros, que se actualizan por separado: la exclusión de versiones y aggrega inspect leen tu índice local del registro, que actualiza aggrega registry update, mientras que aggrega build lee el marcador registrado en el lockfile, que actualiza aggrega pull. Lo que aggrega pull imprime mientras busca no lleva ningún momento de ese tipo — informa de lo que encontró en ese mismo instante.

Por el mismo motivo, la ausencia de una retirada no prueba que no exista ninguna — solo que no se había registrado ninguna la última vez que actualizaste.

Dónde se te informa

Qué comando te informa de una retirada depende de qué registro lee. La tabla de más arriba cubre el marcador registrado en tu lockfile — lo que esta Release fijó. Esta cubre el índice local del registro — lo que un registro publicó —, que es el registro que lee la exclusión de versiones.

ComandoQué te dice sobre una retirada registrada
aggrega registry updateNombra cada marcador que encuentra mientras recorre el registro: el repositorio, la versión sobre la que se registró, la gravedad y si el marcador quedó registrado. Después, cada registro informa de cuántos marcadores contiene ahora su índice.
aggrega searchInforma de la versión que tomaría una resolución en lugar de una revocada, y nombra las versiones revocadas en una columna NOTES. --include-retracted informa en su lugar de la versión publicada más alta.
aggrega inspectImprime la gravedad registrada bajo la entidad, con la versión sobre la que se registró, el motivo, el reemplazo cuando se nombra uno y la fecha de emisión — para cada tipo que resuelve por nombre.
aggrega pullNombra cada versión que omitió, el motivo registrado contra ella y la versión que tomó en su lugar. Una versión que nombraste explícitamente se resuelve igualmente, y la retirada se anuncia en lugar de aplicarse.
aggrega plugin addLo mismo: una versión que elige se filtra en cualquiera de las dos vías por las que resuelve una, y una versión que nombras como <name>:<version> sigue resolviéndose, con la retirada anunciada. Cuando no se pudieron leer los marcadores, lo indica y declara que las versiones publicadas no se filtraron.
aggrega buildNada de este registro. Lee solo tu lockfile y nunca el índice, así que lo que informa es el marcador registrado contra la versión que fijaste.
aggrega serveNada de este registro. Su propia resolución no consulta los registros de retirada, así que allí todavía puede seleccionarse una versión revocada; publica el marcador del lockfile en tu editor.

Lee las dos últimas filas junto con el resto: un comando te informa de una retirada solo cuando está haciendo algo en lo que la retirada influye — elegir una versión, o mostrarte lo que dijo un publicador. El silencio de un comando que no hace ninguna de las dos cosas no es prueba de que no haya nada registrado.

Un aviso nombra la gravedad que registró el publicador. Un artefacto revocado se informa como retracted; las dos gravedades consultivas se informan como obsoletas, indicando cuál de las dos. Así, lo que vuelves a leer coincide con el valor que se escribió y con el valor con el que configurarías un umbral de detención.

Dos tipos de aviso se mantienen separados porque informan de eventos distintos. Una línea deprecation: te dice algo sobre un artefacto. Una línea retraction: te dice lo que no obtuviste — una versión que se omitió, o un filtrado que no se pudo realizar. Cuando un comando emite ambas sobre el mismo artefacto, son dos hechos y no una misma afirmación hecha dos veces.

Qué resoluciones cubre la exclusión

La exclusión actúa dondequiera que un comando elige una versión por ti. Esa es la regla, y determina si una resolución concreta está cubierta.

aggrega pull la aplica dondequiera que elige una versión para una referencia que no nombraba ninguna — nombre lo que nombre la referencia: una entidad del catálogo, una biblioteca, un Aggregate publicado. Una sola regla las rige todas, así que la versión a la que se resuelve una referencia no depende de qué tipo de referencia la pidió.

aggrega plugin add la aplica en cada vía por la que resuelve una referencia a un plugin no fijada: frente a las versiones publicadas que tu índice local del registro ya contiene, y frente a la lista de versiones en vivo a la que recurre cuando ese índice no contiene el repositorio. Una versión retirada se omite, y la sustitución se anuncia, sea cual sea la vía que la resolvió.

El daemon orientado al editor es la excepción. Resuelve referencias bajo demanda mientras atiende a un editor, y esa resolución elige versiones sin consultar los registros de retirada, así que allí todavía puede seleccionarse una versión registrada como revocada.

Donde no se elige nada, la exclusión no tiene nada sobre lo que actuar: una referencia que nombra una versión exacta se resuelve a esa versión, y la retirada se anuncia en lugar de aplicarse. Tampoco nada de esto cambia lo que se te dice en tiempo de build — aggrega build informa de cada marcador que registra el lockfile, sea cual sea la vía que fijó la versión.

Véase también

  • ./aggrega-sign.md — un marcador se firma mediante su propio digest, así que los modos de firma y las credenciales que necesita cada uno son los descritos allí.
  • ./aggrega-serve.md — el daemon adjunta el mismo marcador en aggrega/deprecateArtifact. El contenido que se solicita en un terminal es obligatorio en una solicitud allí, porque nada en esa superficie puede pedirlo.
  • ./aggrega-mcp.md — la misma capacidad como la herramienta deprecate-artifact, que un asistente puede llamar. Lee lo que esa página dice sobre permitirla antes de hacerlo: una retirada cambia lo que resuelve cada consumidor de ese registro.