Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

aggrega deprecate

Anexar um marcador de descontinuação assinado a um artefato 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

FlagPadrãoDescrição
--from—Arquivo 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, além de replacement e message opcionais. Mutuamente exclusivo com uma referência posicional e com —severity, —reason, —replacement e —message.
--fulcio-url—URL da autoridade certificadora Fulcio para assinatura sem chave. Quando omitida, a instância pública do Fulcio é usada.
--identity-token—Token de identidade OIDC para assinatura sem chave. Opcional em um terminal interativo (um fluxo no navegador obtém um) e no GitHub Actions (o token OIDC do workflow é emitido automaticamente); obrigatório para outros usos não interativos/CI, em que pode ser exportado como AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN.
--key—Caminho para um PEM de chave privada ECDSA P-256 em seu poder, para assinatura offline com chave. Quando omitido, a assinatura sem chave é usada.
--message—Mensagem opcional mantida para auditoria e para o diagnóstico registrado no momento do build; quando não definida, assume o valor de —reason. Recusada junto com —from, cujas entradas trazem a sua própria.
--reason—Motivo legível por pessoas para a descontinuação — por que está descontinuado e o que fazer em vez disso. Obrigatório com uma referência posicional, a menos que uma solicitação interativa o forneça; recusado junto com —from, cujas entradas trazem o seu próprio.
--rekor-url—URL do log de transparência Rekor para assinatura sem chave. Quando omitida, a instância pública do Rekor é usada.
--replacement—Referência opcional ao artefato que substitui o descontinuado. Recusada junto com —from, cujas entradas trazem a sua própria.
--severity—Severidade da descontinuação: uma entre warning, error, retracted. Obrigatória com uma referência posicional, a menos que uma solicitação interativa a forneça; recusada junto com —from, cujas entradas trazem a sua própria.
--timestamp-url—URL opcional da autoridade de carimbo de tempo RFC3161 para assinatura sem chave.

De onde vêm os endpoints de assinatura

As URLs 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 registry, em que um valor definido para o registry do artefato tem precedência sobre o global, campo a campo); uma flag sobrescreve a configuração, e a configuração sobrescreve o padrã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 workspace indica um endpoint. O marcador é assinado exatamente como aggrega sign assina um artefato.

Quando o registry faz uma gravação falhar

Descontinuar um artefato grava no registry duas vezes: o marcador, anexado como referrer do artefato, e depois a assinatura do marcador, anexada como referrer do marcador. Cada gravação é repetida quando o registry ou a rede a faz falhar de um modo em que uma tentativa posterior pode ter sucesso, como um erro do servidor, um tempo limite esgotado ou uma conexão redefinida; aggrega push lista essas falhas. Uma gravação é tentada no máximo três vezes, com meio segundo e depois um segundo de intervalo, e cada tentativa é um novo upload dos mesmos bytes em vez de um reenvio da solicitação que falhou. O carimbo de tempo do marcador é aplicado uma única vez, antes da primeira tentativa, de modo que uma gravação repetida deixa um marcador e uma assinatura, não dois.

A assinatura do marcador, entre as duas gravações, não é repetida como um todo; dentro de uma assinatura keyless, uma solicitação que a autoridade certificadora, o log de transparência ou a autoridade de carimbo de tempo responde com 429 Too Many Requests ou com um erro de servidor é enviada novamente a esse serviço, como descreve aggrega sign. Uma gravação que ainda falha após a última tentativa, ou uma assinatura que falha, interrompe o comando e nomeia a etapa; um marcador já anexado até então permanece anexado sem a assinatura. Com --from, as entradas anexadas antes daquela que falhou permanecem anexadas.

Um arquivo de lote traz 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 arquivo de lote. Por isso, um --severity, --reason, --replacement ou --message passado junto com --from é recusado em vez de ignorado: o comando nomeia cada um dos que foram passados e para antes de o arquivo de lote ser lido, de modo que nenhum marcador é anexado. Coloque o conteúdo nas entradas do arquivo, ou descontinue uma única referência com seus flags de conteúdo.

Um lote é assinado com uma única credencial

Com --from, cada marcador no arquivo de lote é assinado com a mesma credencial: uma única chave em seu poder, ou uma única identidade sem chave solicitada uma vez para o arquivo inteiro. Qual delas uma entrada precisa é decidido pela configuração do registry de sua referência — um signing.key_path que se aplica a esse registry seleciona a chave que ele 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 registry e nenhuma para outro, ou duas chaves diferentes —, nenhum marcador é anexado e o comando nomeia os registries de cada lado. Ele faz isso antes que qualquer identidade seja solicitada e antes que qualquer registry seja lido.

Divida o arquivo em um lote por credencial, ou passe uma única chave com --key, que se aplica a todas as entradas independentemente do que a configuração diga para cada registry. A mensagem é descrita em References signed together need different signing credentials (Referências assinadas juntas precisam de credenciais de assinatura diferentes).

O assinante de cada entrada também é preparado antes que o primeiro marcador seja anexado, de modo que uma chave que não pode ser lida, ou um token de identidade fornecido que não contém nenhum subject utilizável, interrompe o lote sem que nada tenha sido anexado.

O que cada severidade faz

As três severidades formam um conjunto ordenado — warning, depois error, depois retracted — e se dividem em dois níveis que diferem em quando agem.

warning e error são níveis consultivos. Um marcador em qualquer uma dessas severidades nunca muda a versão para a qual uma referência é resolvida. Ele é registrado quando você executa aggrega pull, e toda superfície que lê o lockfile o informa.

Cada uma dessas superfícies informa toda referência descontinuada que o lockfile fixa, qualquer que seja a severidade, nomeando a referência, sua severidade, sua mensagem e quando o registro foi observado:

SuperfícieO que ela faz com um marcador registrado
aggrega buildInforma-o, e é interrompido se você configurou uma interrupção nessa severidade.
aggrega validate --releaseInforma-o. O veredito não muda.
aggrega lint --releaseInforma-o. O veredito não muda.
aggrega servePublica-o no seu editor como um aviso enquanto o Aggregate está aberto. Um marcador nomeia uma referência ou um plugin, e não um documento no seu workspace, então ele permanece no Aggregate; apenas as falhas de mapeamento do próprio Manifest são mostradas no Manifest.
A ferramenta build nativa para IAInforma-o, e recusa se você configurou uma interrupção nessa severidade.
As ferramentas describe e validate nativas para IAInformam-no junto com a própria saída.

Se um marcador também interrompe um build é uma configuração separada: build.halt_on_deprecated_severity não é definida por padrão, então nada é interrompido, e defini-la como uma severidade interrompe nessa severidade e nas superiores. Ela rege o build — aggrega build e a ferramenta de build nativa para IA, que é a mesma operação — e nada mais: as superfícies que informam nomeiam o marcador e seguem em frente de qualquer forma. Aumentar o limite nunca reduz o que é informado a você, em nenhuma superfície — você continua recebendo o aviso de tudo abaixo dele e de tudo o que a interrupção não cobre.

Alguns plugins são registrados em outro lugar, e seus marcadores vêm de lá. Um anexo plugins.linter, e um anexo plugins.governance em um papel ir-verdict ou render-verdict, não moldam nada da saída renderizada, então são fixados em plugins-trust.yaml ao lado do lockfile em vez de no próprio lockfile. Cada registro ali contém o marcador descoberto para o plugin que nomeia, junto com sua identidade, e aggrega pull registra um da mesma forma que registra um marcador em uma linha do lockfile.

aggrega build, aggrega lint --release e aggrega validate --release leem os dois registros, então um plugin descontinuado é nomeado ali assim como uma referência descontinuada, e build.halt_on_deprecated_severity rege ambos da mesma forma. Vale a pena conhecer duas diferenças. O aviso para um plugin assim não diz quando o registro foi observado — esse arquivo não contém nenhum carimbo de tempo, e é isso que permite reproduzi-lo byte a byte —, então ele nomeia em vez disso de onde veio a informação e o comando que a atualiza. E uma entrada ali nunca é reescrita por um pull comum: um marcador recém-publicado é adicionado ao registro que o plugin já tem, enquanto a identidade a que ele está vinculado permanece inalterada até você pedir para alterá-la com aggrega pull --upgrade.

retracted é o nível de retirada, e ele também age mais cedo. Uma versão registrada como retirada é removida da consideração quando aggrega pull escolhe uma versão para uma referência que não nomeava nenhuma. Se outra versão publicada satisfaz a referência, essa versão é usada e o pull informa isso, nomeando a versão que pulou, o motivo registrado contra ela e a versão que usou em seu lugar. Se não resta nenhuma versão publicada que satisfaça a referência, o pull é interrompido e diz que todas as candidatas foram retiradas — ele não informa a entidade como ausente e nunca recorre a outra em silêncio.

Nomear uma versão explicitamente substitui a retirada

Uma referência que nomeia uma versão exata sempre é resolvida para essa versão, tenha ela sido retirada ou não. Nomear a versão é a substituição, então não há uma configuração separada para desativar a exclusão — e uma versão fixada por um aggrega pull anterior continua sendo resolvida exatamente pelo mesmo motivo.

O pull diz isso abertamente quando a versão que você nomeou foi retirada, para que o build que já se comprometeu com ela continue funcionando enquanto você ainda pode ver por que talvez queira mudar.

Registros de retirada são um snapshot, não uma resposta em tempo real

Um artefato publicado é imutável, mas uma retirada não: uma versão pode ser retirada depois da última vez que você verificou. A exclusão lê o que seu workspace registrou na última vez em que construiu seu índice local do registry, então ela protege você de selecionar uma versão sabidamente retirada. Ela não pode dizer a você que uma versão não está retirada neste momento.

Cada informe de um marcador registrado anteriormente indica quando esse registro foi observado, de modo que um registro desatualizado pode ser distinguido de um recente, e cada um nomeia o comando que o atualiza. Dois registros são mantidos e atualizados separadamente: a exclusão de versões e aggrega inspect leem seu índice local do registry, que aggrega registry update atualiza, enquanto aggrega build lê o marcador registrado no lockfile, que aggrega pull atualiza. O que aggrega pull imprime enquanto procura não traz nenhum momento desse tipo — ele informa o que encontrou naquele instante.

Pelo mesmo motivo, a ausência de uma retirada não é prova de que não exista nenhuma — apenas de que nenhuma havia sido registrada na última vez que você atualizou.

Onde você é informado

Qual comando informa você sobre uma retirada depende de qual registro ele lê. A tabela mais acima cobre o marcador registrado no seu lockfile — o que esta Release fixou. Esta cobre o índice local do registry — o que um registry publicou —, que é o registro lido pela exclusão de versões.

ComandoO que ele informa sobre uma retirada registrada
aggrega registry updateNomeia cada marcador que encontra ao percorrer o registry: o repositório, a versão em que foi registrado, a severidade e se o marcador foi registrado. Em seguida, cada registry informa quantos marcadores seu índice contém agora.
aggrega searchInforma a versão que uma resolução tomaria em vez de uma revogada, e nomeia as versões revogadas em uma coluna NOTES. --include-retracted informa, em vez disso, a versão publicada mais alta.
aggrega inspectImprime a severidade registrada abaixo da entidade, com a versão em que foi registrada, o motivo, a substituta quando uma é indicada e a data de emissão — para cada tipo que resolve por nome.
aggrega pullNomeia cada versão que ignorou, o motivo registrado contra ela e a versão que tomou no lugar. Uma versão que você nomeou explicitamente ainda é resolvida, e a retirada é anunciada em vez de aplicada.
aggrega plugin addO mesmo: uma versão que ele escolhe é filtrada em qualquer uma das duas vias pelas quais resolve uma, e uma versão que você nomeia como <name>:<version> ainda é resolvida, com a retirada anunciada. Quando os marcadores não puderam ser lidos, ele informa isso e declara que as versões publicadas não foram filtradas.
aggrega buildNada deste registro. Ele lê apenas o seu lockfile e nunca o índice, então o que informa é o marcador registrado contra a versão que você fixou.
aggrega serveNada deste registro. Sua própria resolução não consulta os registros de retirada, então uma versão revogada ainda pode ser selecionada ali; ele publica o marcador do lockfile no seu editor.

Leia as duas últimas linhas junto com as demais: um comando informa você sobre uma retirada apenas quando está fazendo algo em que a retirada interfere — escolher uma versão ou mostrar o que um publicador declarou. O silêncio de um comando que não faz nenhuma das duas coisas não é evidência de que nada está registrado.

Um aviso nomeia a severidade que o publicador registrou. Um artefato revogado é informado como retracted; as duas severidades consultivas são informadas como obsoletas, indicando qual das duas. Assim, o que você lê de volta corresponde ao valor que foi escrito e ao valor com que você configuraria um limite de interrupção.

Dois tipos de aviso são mantidos separados porque informam eventos diferentes. Uma linha deprecation: diz algo sobre um artefato. Uma linha retraction: diz o que você não obteve — uma versão que foi ignorada, ou uma filtragem que não pôde ser realizada. Quando um comando emite ambas sobre o mesmo artefato, são dois fatos, e não uma mesma afirmação feita duas vezes.

Quais resoluções a exclusão cobre

A exclusão atua sempre que um comando escolhe uma versão para você. Essa é a regra, e ela determina se uma resolução específica está coberta.

aggrega pull a aplica 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 do catálogo, uma biblioteca, um Aggregate publicado. Uma única regra rege todas elas, então a versão para a qual uma referência é resolvida não depende de qual tipo de referência a solicitou.

aggrega plugin add a aplica em cada via pela qual resolve uma referência de plugin não fixada: em relação às versões publicadas que seu índice local do registry já contém, e em relação à lista de versões ao vivo que ele consulta 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 voltado ao editor é a exceção. Ele resolve referências sob demanda enquanto atende um editor, e essa resolução escolhe versões sem consultar os registros de retirada, então uma versão registrada como revogada ainda pode ser selecionada ali.

Onde nada é escolhido, a exclusão não tem sobre o que atuar: uma referência que nomeia uma versão exata é resolvida para essa versão, e a retirada é anunciada em vez de aplicada. Nada disso muda também o que você é informado no momento do build — aggrega build informa cada marcador que o lockfile registra, seja qual for a via que fixou a versão.

Veja também

  • ./aggrega-sign.md — um marcador é assinado por seu próprio digest, então os modos de assinatura e as credenciais que cada um exige são os descritos ali.
  • ./aggrega-serve.md — o daemon anexa o mesmo marcador em aggrega/deprecateArtifact. O conteúdo solicitado em um terminal é obrigatório em uma requisição ali, porque nada nessa superfície pode solicitá-lo.
  • ./aggrega-mcp.md — a mesma capacidade como a ferramenta deprecate-artifact, que um assistente pode chamar. Leia o que essa página diz sobre permiti-la antes de fazê-lo: uma retirada muda o que cada consumidor desse registry resolve.