aggrega deprecate
Anexar um marcador de descontinuação assinado a um artefacto já publicado
Sinopse
aggrega deprecate <reference> [flags]Descrição
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
| Flag | Predefinição | Descrição |
|---|---|---|
--from | — | Ficheiro de lote (YAML, ou JSON como subconjunto) cuja lista de nível superior anexa um marcador por entrada. Cada entrada contém reference, severity e reason, e ainda, opcionalmente, replacement e message. Mutuamente exclusivo com uma referência posicional e com —severity, —reason, —replacement e —message. |
--fulcio-url | — | URL da autoridade de certificação Fulcio para a assinatura sem chave. Quando omitido, é usada a instância pública do Fulcio. |
--identity-token | — | Token de identidade OIDC para a assinatura sem chave. Opcional num terminal interativo (um fluxo no browser obtém um) e no GitHub Actions (o token OIDC do workflow é emitido automaticamente); obrigatório para outros usos não interativos/em CI, onde pode em alternativa ser exportado como AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN. |
--key | — | Caminho para um PEM de chave privada ECDSA P-256 detida, para assinatura offline com chave. Quando omitido, é usada a assinatura sem chave. |
--message | — | Mensagem opcional mantida para auditoria e para o diagnóstico registado no momento da compilação; por predefinição, —reason quando não definida. Recusada juntamente com —from, cujas entradas trazem a sua própria. |
--reason | — | Motivo legível por humanos para a descontinuação — porque está descontinuado e o que fazer em alternativa. Obrigatório com uma referência posicional, a menos que um pedido interativo o forneça; recusado juntamente com —from, cujas entradas trazem o seu próprio. |
--rekor-url | — | URL do registo de transparência Rekor para a assinatura sem chave. Quando omitido, é usada a instância pública do Rekor. |
--replacement | — | Referência de artefacto opcional que substitui o descontinuado. Recusada juntamente com —from, cujas entradas trazem a sua própria. |
--severity | — | Severidade da descontinuação: warning, error ou retracted. Obrigatória com uma referência posicional, a menos que um pedido interativo a forneça; recusada juntamente com —from, cujas entradas trazem a sua própria. |
--timestamp-url | — | URL opcional da autoridade de carimbo temporal RFC3161 para a assinatura sem chave. |
De onde vêm os endpoints de assinatura
Os URL do Fulcio e do Rekor da assinatura sem chave e o caminho da chave da assinatura com chave também podem vir do bloco signing: do .aggrega-config.yaml (global e por registo, em que um valor definido para o registo do artefacto tem precedência sobre o global, campo a campo); uma flag substitui a configuração, e a configuração substitui a predefinição public-good. Assim, as instâncias public-good indicadas na tabela de flags só são usadas quando nem uma flag nem a configuração do seu espaço de trabalho indica um endpoint. O marcador é assinado exatamente como aggrega sign assina um artefacto.
Quando o registo falha uma escrita
Descontinuar um artefacto escreve duas vezes no registo: o marcador, anexado como referenciador do artefacto, e depois a assinatura do marcador, anexada como referenciador do marcador. Cada escrita é repetida quando o registo ou a rede a fazem falhar de uma forma em que uma tentativa posterior pode ter êxito, como um erro do servidor, um tempo limite excedido ou uma ligação reposta; aggrega push lista essas falhas. Uma escrita é tentada no máximo três vezes, com meio segundo e depois um segundo de intervalo, e cada tentativa é um novo carregamento dos mesmos bytes e não um reenvio do pedido que falhou. O carimbo temporal do marcador é aplicado uma vez, antes da primeira tentativa, pelo que uma escrita repetida deixa um marcador e uma assinatura, não dois.
A assinatura do marcador, entre as duas escritas, não é repetida no seu todo; dentro de uma assinatura keyless, um pedido a que a autoridade de certificação, o registo de transparência ou a autoridade de carimbo temporal responda com 429 Too Many Requests ou com um erro de servidor é enviado novamente a esse serviço, como descreve aggrega sign. Uma escrita que continue a falhar após a última tentativa, ou uma assinatura que falhe, para o comando e nomeia o passo; um marcador já anexado nessa altura permanece anexado sem a sua assinatura. Com --from, as entradas anexadas antes daquela que falhou permanecem anexadas.
Um ficheiro de lote contém o conteúdo de cada marcador
Com --from, a severidade, o motivo, a substituição e a mensagem de cada marcador vêm da sua própria entrada no ficheiro de lote. Um --severity, --reason, --replacement ou --message passado juntamente com --from é, por isso, recusado em vez de ignorado: o comando nomeia cada um dos que foram passados e para antes de o ficheiro de lote ser lido, pelo que nenhum marcador é anexado. Coloque o conteúdo nas entradas do ficheiro, ou descontinue uma única referência com as respetivas flags de conteúdo.
Um lote é assinado com uma única credencial
Com --from, todos os marcadores do ficheiro de lote são assinados com a mesma credencial: uma única chave detida, ou uma única identidade sem chave pedida uma vez para todo o ficheiro. Qual delas uma entrada precisa é decidido pela configuração do registo da sua referência — um signing.key_path que se aplique a esse registo seleciona a chave que nomeia, e quando nenhum se aplica o marcador é assinado sem chave. Quando as entradas precisariam de credenciais diferentes — a configuração nomeia uma chave para um registo e nenhuma para outro, ou duas chaves diferentes — nenhum marcador é anexado e o comando nomeia os registos de cada lado. Fá-lo antes de qualquer identidade ser pedida e antes de qualquer registo ser lido.
Divida o ficheiro num lote por credencial, ou passe uma chave com --key, que se aplica a todas as entradas independentemente do que a configuração diga para cada registo. A mensagem é descrita em References signed together need different signing credentials (As referências assinadas em conjunto precisam de credenciais de assinatura diferentes).
O signatário de cada entrada é também preparado antes de o primeiro marcador ser anexado, pelo que uma chave que não possa ser lida, ou um token de identidade fornecido que não contenha um sujeito utilizável, para o lote sem nada anexado.
O que cada severidade faz
As três severidades formam um conjunto ordenado — warning, depois error, depois retracted — e dividem-se em dois níveis que diferem no momento em que atuam.
warning e error são níveis consultivos. Um marcador com qualquer destas severidades nunca altera a versão para a qual uma referência é resolvida. É registado quando se executa aggrega pull, e todas as superfícies que leem o lockfile o reportam.
Cada uma dessas superfícies reporta todas as referências descontinuadas que o lockfile fixa, seja qual for a severidade, nomeando a referência, a sua severidade, a sua mensagem e o momento em que o registo foi observado:
| Superfície | O que faz com um marcador registado |
|---|---|
aggrega build | Reporta-o e para se tiver sido configurada uma paragem nessa severidade. |
aggrega validate --release | Reporta-o. O veredicto não se altera. |
aggrega lint --release | Reporta-o. O veredicto não se altera. |
aggrega serve | Publica-o no seu editor como um aviso enquanto o Aggregate estiver aberto. Um marcador indica uma referência ou um plugin, e não um documento na sua área de trabalho, pelo que permanece no Aggregate; apenas as falhas de mapeamento do próprio Manifest são mostradas no Manifest. |
A ferramenta build nativa de IA | Reporta-o e recusa se tiver sido configurada uma paragem nessa severidade. |
As ferramentas describe e validate nativas de IA | Reportam-no juntamente com a sua própria saída. |
Se um marcador também para uma compilação é uma definição separada: build.halt_on_deprecated_severity não está definida por predefinição, pelo que nada para, e defini-la com uma severidade faz parar nessa severidade e acima. Rege a compilação — aggrega build e a ferramenta de compilação nativa de IA, que é a mesma operação — e nada mais: as superfícies de reporte nomeiam o marcador e prosseguem em qualquer caso. Subir o limiar nunca reduz o que é comunicado, em nenhuma superfície — continua a receber o aviso para tudo o que está abaixo dele e para tudo o que a paragem não abrange.
Alguns plugins são registados noutro local, e os seus marcadores vêm daí. Uma anexação plugins.linter, e uma anexação plugins.governance numa função ir-verdict ou render-verdict, não moldam nada da saída renderizada, pelo que são fixadas em plugins-trust.yaml ao lado do lockfile e não no próprio lockfile. Cada registo aí contém o marcador descoberto para o plugin que nomeia, juntamente com a sua identidade, e aggrega pull regista-o da mesma forma que regista um marcador numa linha do lockfile.
aggrega build, aggrega lint --release e aggrega validate --release leem ambos os registos, pelo que um plugin descontinuado é aí nomeado tal como uma referência descontinuada, e build.halt_on_deprecated_severity rege ambos da mesma forma. Há duas diferenças que vale a pena conhecer. O aviso para um plugin destes não indica quando o registo foi observado — esse ficheiro não contém quaisquer carimbos temporais, o que lhe permite ser reproduzido byte a byte — pelo que nomeia, em vez disso, de onde veio o facto e o comando que o atualiza. E uma entrada aí nunca é reescrita por um pull normal: um marcador recém-publicado é acrescentado ao registo que o plugin já tem, enquanto a identidade a que está vinculado se mantém até que se peça a sua alteração com aggrega pull --upgrade.
retracted é o nível de retirada, e também atua mais cedo. Uma versão registada como retirada é excluída da consideração quando aggrega pull escolhe uma versão para uma referência que não nomeou nenhuma. Se outra versão publicada satisfizer a referência, essa versão é usada e o pull indica-o, nomeando a versão que ignorou, o motivo registado contra ela e a versão que usou em seu lugar. Se não restar nenhuma versão publicada que satisfaça a referência, o pull para e indica que todos os candidatos foram retirados — não reporta a entidade como em falta e nunca recorre a uma alternativa em silêncio.
Nomear explicitamente uma versão sobrepõe-se à retirada
Uma referência que nomeia uma versão exata resolve sempre para essa versão, quer tenha sido retirada quer não. Nomear a versão é a sobreposição, pelo que não há nenhuma definição separada para desativar a exclusão — e uma versão fixada por um aggrega pull anterior continua a ser resolvida exatamente pela mesma razão.
O pull indica-o expressamente quando a versão nomeada foi retirada, para que a compilação que já se comprometeu com ela continue a funcionar e continue a ser possível ver porque se poderá querer mudar.
Os registos de retirada são um instantâneo, não uma resposta em tempo real
Um artefacto publicado é imutável, mas uma retirada não o é: uma versão pode ser retirada depois da última consulta. A exclusão lê o que o espaço de trabalho registou da última vez que construiu o seu índice local de registos, pelo que protege contra a seleção de uma versão que se sabe ter sido retirada. Não consegue indicar que uma versão não está retirada neste momento.
Cada reporte de um marcador registado anteriormente indica quando esse registo foi observado, para que um registo desatualizado seja distinguível de um recente, e cada um nomeia o comando que o atualiza. São mantidos dois registos, que se atualizam separadamente: a exclusão de versões e aggrega inspect leem o índice local de registos, que aggrega registry update atualiza, enquanto aggrega build lê o marcador registado no lockfile, que aggrega pull atualiza. O que aggrega pull imprime enquanto procura não contém esse momento — está a reportar o que encontrou nesse preciso instante.
Pela mesma razão, a ausência de uma retirada não é prova de que não exista nenhuma — apenas de que nenhuma tinha sido registada na última atualização.
Onde é comunicado
O comando que comunica uma retirada decorre do registo que lê. A tabela mais acima abrange o marcador registado no lockfile — o que esta Release fixou. Esta abrange o índice local de registos — o que um registo publicou —, que é o registo que a exclusão de versões lê.
| Comando | O que comunica sobre uma retirada registada |
|---|---|
aggrega registry update | Nomeia cada marcador que encontra ao percorrer o registo: o repositório, a versão em que foi registado, a severidade e se o marcador foi registado. Cada registo reporta depois quantos marcadores o seu índice contém agora. |
aggrega search | Reporta a versão que uma resolução usaria em vez de uma retirada, e nomeia as versões retiradas numa coluna NOTES. --include-retracted reporta, em vez disso, a versão publicada mais alta. |
aggrega inspect | Imprime a severidade registada sob a entidade, com a versão em que foi registada, o motivo, a substituição quando é nomeada e a data em que foi emitida — para todos os tipos que resolve por nome. |
aggrega pull | Nomeia cada versão que ignorou, o motivo registado contra ela e a versão que usou em seu lugar. Uma versão nomeada explicitamente continua a ser resolvida, e a retirada é anunciada em vez de aplicada. |
aggrega plugin add | O mesmo: uma versão que escolhe é filtrada em qualquer das vias pelas quais resolve uma, e uma versão nomeada como <name>:<version> continua a ser resolvida, com a retirada anunciada. Quando os marcadores não puderam ser lidos, indica-o e declara que as versões publicadas não foram filtradas. |
aggrega build | Nada deste registo. Lê apenas o lockfile e nunca o índice, pelo que o que reporta é o marcador registado contra a versão fixada. |
aggrega serve | Nada deste registo. A sua própria resolução não consulta os registos de retirada, pelo que aí ainda pode ser selecionada uma versão retirada; publica no editor o marcador do lockfile. |
Leia as duas últimas linhas em conjunto com as restantes: um comando só comunica uma retirada quando está a fazer algo em que a retirada tem influência — escolher uma versão ou mostrar o que um publicador disse. O silêncio de um comando que não faz nenhuma destas coisas não é prova de que nada esteja registado.
Um aviso nomeia a severidade que o publicador registou. Um artefacto retirado é reportado como retracted; as duas severidades consultivas são reportadas como descontinuadas, indicando qual das duas. Assim, o que se lê corresponde ao valor que foi escrito e ao valor com que se configuraria um limiar de paragem.
Dois tipos de aviso são mantidos separados porque reportam acontecimentos diferentes. Uma linha deprecation: diz algo sobre um artefacto. Uma linha retraction: diz o que não se obteve — uma versão que foi ignorada, ou uma filtragem que não pôde ser efetuada. Quando um comando emite ambas sobre o mesmo artefacto, são dois factos e não uma afirmação feita duas vezes.
Que resoluções a exclusão abrange
A exclusão atua sempre que um comando escolhe uma versão pelo utilizador. É essa a regra, e decide se uma determinada resolução está abrangida.
aggrega pull aplica-a sempre que escolhe uma versão para uma referência que não nomeou nenhuma — seja o que for que a referência nomeie: uma entidade de catálogo, uma biblioteca, um Aggregate publicado. Uma única regra rege todas elas, pelo que a versão para a qual uma referência é resolvida não depende do tipo de referência que a pediu.
aggrega plugin add aplica-a em todas as vias pelas quais resolve uma referência de plugin não fixada: contra as versões publicadas que o índice local de registos já contém, e contra a lista de versões em tempo real a que recorre quando esse índice não contém o repositório. Uma versão retirada é ignorada, e a substituição anunciada, seja qual for a via que a resolveu.
O daemon orientado para editores é a exceção. Resolve referências a pedido enquanto serve um editor, e essa resolução escolhe versões sem consultar os registos de retirada, pelo que aí ainda pode ser selecionada uma versão registada como retirada.
Quando nada é escolhido, não há nada sobre o qual a exclusão possa atuar: uma referência que nomeia uma versão exata resolve para essa versão, e a retirada é anunciada em vez de aplicada. Nada disto altera também o que é comunicado no momento da compilação — aggrega build reporta todos os marcadores que o lockfile regista, seja qual for a via que fixou a versão.
Ver também
- ./aggrega-sign.md — um marcador é assinado pelo seu próprio digest, pelo que os modos de assinatura e as credenciais de que cada um precisa são os descritos aí.
- ./aggrega-serve.md — o daemon anexa o mesmo marcador em
aggrega/deprecateArtifact. O conteúdo que é pedido num terminal é obrigatório num pedido aí, porque nada nessa superfície o pode pedir. - ./aggrega-mcp.md — a mesma capacidade que a ferramenta
deprecate-artifact, que um assistente pode chamar. Leia o que essa página diz sobre permiti-la antes de o fazer: uma retirada altera o que todos os consumidores desse registo resolvem.