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 push

aggrega push publica uma entidade de catálogo em um registry OCI, onde outros workspaces podem resolvê-la com aggrega pull.

O que ele faz

aggrega push lê um único YAML de entidade, empacota-o para transporte e o envia para <registry>/<kind>/<metadata.name>:<metadata.version>, com o caminho do repositório em minúsculas; uma Recipe ou FeatureRecipe leva seu spec.capability, e um Plugin seu metadata.pluginType, como um segmento entre o tipo e o nome. Execute aggrega push --list-kinds para obter os tipos de entidade que o binário instalado publica — um tipo por linha, ordenados, e nada mais, de modo que um script pode lê-lo diretamente. O conjunto abrange os tipos de autoria do catálogo junto com o Aggregate, um módulo reutilizável, e o Plugin, uma referência endereçada por conteúdo a um artefato WebAssembly que o compilador encaminha e o runtime executa. O Plugin é um artefato publicável estrutural, e não um tipo de autoria do catálogo. A publicabilidade é uma propriedade da entidade, não de como ela é usada: um Aggregate é publicável seja ele referenciado depois como o spec.aggregate de nível superior de uma Release, seja aninhado no bloco aggregates: de outro Aggregate. Release e Manifest são entradas do lado da implantação, não artefatos de catálogo, e são rejeitados.

Empacotamento

Um push publica o documento da entidade e os arquivos que a própria entidade nomeia ao lado dele — e nada mais em seu diretório. Os arquivos que uma entidade nomeia são:

  • para uma Recipe ou FeatureRecipe, seu source: local — um diretório viaja com cada arquivo dentro dele que as regras de exclusão registradas em seu entity.lock mantêm, como descreve Quais arquivos são distribuídos com uma entidade; cada arquivo que suas entradas valuesMapping:, workload: e artifacts: importam com $import:; e o entity.lock ao lado dela;
  • para um Component ou uma Feature, cada arquivo de schema que seu spec.schema, um pilar ou um socket usesSchema importa com $import:, incluindo cada arquivo que um arquivo importado importa por sua vez.

Um Aggregate, um Plugin e os tipos de biblioteca não nomeiam nenhum arquivo ao lado do seu documento. Uma nota, um README, os arquivos de outra entidade ou a saída de um build que estejam no diretório não são publicados, seja qual for o nome. Um link simbólico entre os arquivos que uma entidade nomeia é recusado em vez de seguido — A symbolic link sits among the files an entity carries (Há um link simbólico entre os arquivos que uma entidade carrega) —, e o mesmo vale para um caminho que uma entidade nomeia por meio de um diretório que é um link que leva para fora do diretório da entidade, antes que qualquer coisa seja empacotada — A path names content outside the entity’s own directory (Um caminho nomeia conteúdo fora do diretório da própria entidade).

A forma decorre disso. Uma entidade que não nomeia nada é publicada como seu documento, inalterado, sob o media type +yaml do seu tipo. Uma que nomeia um arquivo é publicada como um .tar.gz contendo o documento e esses arquivos em suas posições no diretório, sob o media type +tar+gz do seu tipo. Assim, uma Recipe cujo conteúdo é todo inline é publicada como seu documento, e um Component cujo schema é importado de um arquivo é publicado como um arquivo compactado. Catálogo e registry §6 lista os dois media types para cada tipo.

Cada arquivo em um arquivo compactado tem o modo 0644 e nenhum timestamp, sejam quais forem seus bits de permissão em disco. Um checkout grava os arquivos com seus próprios bits de permissão, e um sistema que não registra nenhum bit de execução faz checkout como arquivo comum do que outro sistema faz checkout como executável, então o arquivo compactado não leva nenhum modo lido do disco: dois checkouts de um mesmo commit publicam os mesmos arquivos, seja qual for sua umask e o sistema em que foram feitos, e alternar o bit de execução de um script não muda nada do que é publicado.

Um push emite um aviso para cada entrada de um arquivo compactado que o Windows não consegue conter como está escrita — um caminho com uma parte com nome de dispositivo, como CON, AUX ou NUL, em qualquer combinação de maiúsculas e minúsculas e com qualquer extensão em seguida, como aux/x.yaml, ou uma parte que termina em ponto ou espaço, como report.. No Windows, aggrega se recusa a descompactar uma entrada assim, de modo que um workspace Windows não pode usar a versão. O aviso é gravado no erro padrão em todas as plataformas, uma linha por entrada, antes do próprio relato da publicação; o nome de arquivo do próprio documento da entidade é avaliado junto com os arquivos que ela nomeia, e uma entidade que não nomeia nada é publicada apenas como seu documento e nunca recebe aviso. Ele não recusa nada: o push prossegue ou é recusado exatamente como seria sem ele, e --dry-run avisa da mesma forma. A published archive carries an entry Windows cannot use (Um arquivo compactado publicado contém uma entrada que o Windows não consegue usar) mostra a linha e o que fazer a respeito.

Um source: local escrito como template leva o diretório inteiro. Um template como ./charts/{{ .values.flavour }} só nomeia um diretório quando uma Release o preenche, então nenhuma publicação pode saber qual será. Uma entidade assim leva cada arquivo do seu próprio diretório que suas regras de exclusão registradas mantêm — nunca seu .aggregaignore, cujas regras viajam dentro do lock — e o push informa isso abaixo dos seus outros dados:

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 it

O que não é nomeado não viaja, e quem descobre isso é um consumidor. Um arquivo do qual a entidade depende sem nomeá-lo por meio de um dos campos acima não está na publicação, e o build de um consumidor falha indicando o caminho ausente dentro do seu slot de cache — não o seu push. Nomeie cada arquivo de que a entidade precisa por meio de um desses campos.

Cada arquivo publicado é nomeado no manifesto do artefato, de modo que um cliente OCI genérico como oras o grava em um arquivo com esse nome: entity.yaml para uma entidade publicada como seu documento, entity.tar.gz para uma publicada com seus arquivos e, para um Plugin, entity.yaml para a entidade ao lado de entity.wasm para seu executável. O nome decorre do media type, não do arquivo a partir do qual você publica, de modo que o mesmo conteúdo publicado a partir de um arquivo renomeado publica o mesmo artefato. Catálogo e registry §6 lista cada forma publicada e o arquivo com que cada uma chega.

Uma URL source: remota em uma Recipe (uma referência a um chart OCI, uma URL de chart ou de fragmento HTTPS, um módulo Git) é preservada literalmente no YAML publicado; ela não é obtida nem incorporada ao artefato. Os consumidores resolvem e fixam as fontes remotas de forma independente no momento do seu próprio pull. Isso mantém a distribuição de entidades de catálogo e a resolução de artefatos de fonte como preocupações separadas.

Um Aggregate é publicado como seu próprio documento único: um subaggregate que ele referencia em aggregates: não é incluído no artefato. Cada subaggregate é um Aggregate publicado separadamente que os consumidores resolvem e fixam de forma independente no momento do pull, por identidade — o mesmo princípio de separação da distribuição que se aplica às fontes remotas.

Uma entidade por diretório

Um arquivo compactado contém o arquivo da entidade entre os arquivos que ela nomeia, então a entidade precisa ser encontrada novamente na extração. Um consumidor a encontra pelo preâmbulo que ela carrega: o documento no topo do pacote cujo kind: é um tipo de entidade publicável é a entidade. O arquivo em que ela é escrita pode ter qualquer nome — recipe.yaml é a convenção do catálogo, não um requisito —, e um fragmento compose, um template de chart ou um manifesto Kubernetes ao lado da entidade não é confundido com ela, porque esses declaram outra coisa ou nenhum tipo. Documentos de entidade mais abaixo, dentro de uma árvore source/, são conteúdo que a entidade distribui, e não a própria entidade, e nunca são considerados.

Um push recusa uma entidade que compartilha seu diretório com outra entidade. Cada tipo tem um diretório próprio, exceto Aggregate, Release e Manifest, que a raiz de um workspace contém lado a lado. Para qualquer outro tipo, um push verifica, antes de fazer qualquer outra coisa com a entidade — antes da etapa de pin, da política de assinatura e do pacote —, que nenhum outro documento de entidade está no mesmo diretório, e recusa caso contrário, indicando cada entidade que atrapalha, quer o push tenha sido solicitado a fixar pins ou não. aggrega pin recusa o mesmo diretório com as mesmas palavras; a parada é An entity shares its directory with another entity (Uma entidade compartilha seu diretório com outra entidade). Um documento de nenhum tipo de entidade ao lado da entidade — um arquivo de chart, um fragmento compose, um README — não atrapalha, nem qualquer coisa em um subdiretório. Cada documento ao lado da entidade é lido apenas de dentro do workspace ou, para uma entidade que você nomeia fora dele, de dentro do diretório da própria entidade, de modo que um que é um link que leva para fora para o push indicando o link, sem lê-lo, como estabelece o limite do workspace.

A regra é o que mantém um entity.lock pertencendo a uma única entidade: o nome de arquivo do lock é o mesmo para todas as entidades, então duas entidades escritas em um mesmo diretório compartilhariam o único lock para o qual há espaço. Ela só é avaliada quando algo é produzido a partir do diretório, de modo que um diretório com várias entidades ainda é carregado, passa pelo lint e faz build.

O nome do diretório não é avaliado. Uma entidade sozinha em seu diretório é publicada em sua metadata.version, onde quer que esse diretório esteja; <name>/<version>/, o layout que o catálogo da biblioteca padrão segue, é uma convenção. Um artefato que outro cliente publicou a partir de um diretório com duas entidades ainda é lido com segurança: um pull dele para indicando os dois documentos em vez de responder com qualquer um deles, conforme catalogado em errors/fatal-halts.md.

Ler a entidade antes de empacotá-la

Um push lê um Component, uma Feature, uma Recipe ou uma FeatureRecipe da mesma forma que um build os lê, e recusa o que essa leitura recusa — pelo mesmo motivo, com o mesmo código curto, antes que o pacote seja construído e antes que o registry de destino seja contatado. Assim, um documento que não atende ao schema do seu tipo, um caminho que nomeia conteúdo fora do diretório da própria entidade e um schema que um Component ou uma Feature importa com $import: e que está ausente ou não pode ser usado são recusados na publicação em vez de publicados. Cada um deles é uma entidade que o primeiro build dos seus consumidores recusaria; um caminho que sai do diretório também nomeia um arquivo que não viajaria com a entidade, porque cada arquivo que uma publicação carrega é tirado do diretório da própria entidade — consulte A path names content outside the entity’s own directory (Um caminho nomeia conteúdo fora do diretório da própria entidade).

Uma Recipe ou FeatureRecipe é lida dessa forma enquanto seus pins são comparados, como descreve a próxima seção, de modo que a leitura acontece quer o push seja solicitado a fixar pins ou não, e quer a entidade tenha algo a fixar ou não. Cada um dos quatro tipos também é lido dessa forma imediatamente antes de seu pacote ser construído, porque é essa leitura que diz quais arquivos ele nomeia. Um Aggregate e uma biblioteca não nomeiam nenhum arquivo e não são lidos dessa forma. Um Plugin também não nomeia nenhum arquivo, e é lido em relação ao schema do seu tipo antes do seu .wasm, como descreve Publicar um Plugin.

Publicar um Plugin

Um Plugin é publicado junto com seu .wasm, indicado por --plugin, e um push avalia os dois antes que qualquer byte seja publicado ou que o registry seja contatado. --dry-run os avalia exatamente como uma publicação.

A entidade é lida primeiro em relação ao schema do seu tipo, da forma como um carregamento do catálogo a lê, antes que o .wasm seja lido. Assim, uma metadata.version que não é uma versão semântica — um simples commit como 415148e — é recusada sob a própria condição do schema, indicando o campo, assim como qualquer outro desvio do schema, como um spec.abiVersion ausente. O que conta como versão semântica aqui é o padrão do próprio schema para metadata.version; o push não acrescenta nenhuma regra própria.

Em seguida, o .wasm é carregado e confrontado com a entidade. O que ele declara oferecer deve concordar com o que a entidade afirma, o conjunto de comandos e as funções de host que a entidade registra devem corresponder a ele, e a versão que ele declara sobre seu próprio build deve ser igual a metadata.version — consulte A Plugin entity’s recorded version does not match the plugin (A versão registrada de uma entidade Plugin não corresponde ao plugin).

Um .wasm compilado a partir de uma árvore de trabalho com alterações não commitadas é recusado. Um build assim leva a marca -dirty no final da versão que declara — 1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty. Essa é uma versão semântica válida, mas nomeia um commit que não contém o que foi compilado, então ninguém conseguiria recompilar o que foi publicado a partir da versão sob a qual foi publicado. O push a recusa, indicando a versão e a correção: compile o plugin a partir de um checkout limpo do commit que a tag da versão lançada nomeia, para que ele declare a própria versão lançada — e, para lançar a alteração, faça o commit dela com a metadata.version da entidade definida como a nova versão e aplique a tag a esse commit primeiro — em vez de copiar para a entidade a versão que uma recompilação declara. Uma versão de desenvolvimento compilada a partir de um commit, como 1.0.0-3-g1a2b3c4, e uma pré-versão como 1.0.0-rc.1 são ambas publicadas. A recusa é A plugin was built from a working tree with uncommitted changes (Um plugin foi compilado a partir de uma árvore de trabalho com alterações não commitadas).

Fixar antes de publicar

Uma Recipe ou FeatureRecipe carrega os pins das entradas que lê — um source: remoto escrito por completo, um arquivo que uma entrada de artifacts importa, os arquivos de um source: ao lado dela — no entity.lock ao seu lado, e um push publica esse arquivo com a entidade. Fixar é uma etapa que você executa antes de publicar, aggrega pin, e depois você faz commit do lock que ela escreve.

Um push recusa uma entidade cujo lock não registra esses pins. Antes de construir o bundle, um push determina o que a etapa de fixação registraria para a entidade e compara isso com o entity.lock ao lado dela. Onde falta um pin, ou o lock contém um ao qual uma entrada não corresponde mais, o push para antes que qualquer arquivo compactado seja construído ou qualquer registry seja contatado. A recusa nomeia a entidade e cada uma dessas entradas — cada uma um remote source, um imported file ou um local source file — e o que executar: aggrega pin na entidade, --pin-sources no push que você acabou de executar, ou pin_sources_at_push para todo push no workspace. É a mesma recusa que um pull levanta sobre o mesmo lock, An entity reads an input the lock beside it records no pin for (Uma entidade lê uma entrada para a qual o lock ao lado dela não registra nenhum pin), com as soluções próprias de um push. Assim, uma Recipe ou FeatureRecipe que um push publica carrega, dentro do seu bundle, um lock que registra cada pin que a etapa teria registrado no momento em que foi publicada.

Dois tipos de entidade não têm nada a fixar e são publicados sem alterações: uma entidade que não lê nenhuma origem remota, não importa nenhum arquivo e não nomeia nenhuma origem local, e uma Recipe cujas coordenadas de origem remota são preenchidas a partir de um template. Essa origem só nomeia um artefato quando uma Release preenche o template, então seu pin pertence ao lockfile de cada Release, e um push não pede um ao lado da entidade. Um Component, uma Feature, uma biblioteca, um Aggregate ou um Plugin não lê nada do que o lock registra e nunca é recusado aqui.

Comparar o pin de uma origem remota significa buscar a origem, como faz aggrega pin, porque um pin que não corresponde mais só é visível em relação ao que a origem serve agora. Um push sobre uma entidade com essa origem, portanto, alcança o host da origem antes de alcançar o registry. A comparação lê uma Recipe ou FeatureRecipe da mesma forma que a etapa de fixação, por meio do catálogo, de modo que uma que o catálogo se recusa a ler — um documento que falha no schema do seu tipo, por exemplo — é recusada aqui com o motivo do próprio catálogo.

Onde nenhum workspace foi encontrado e nenhum foi indicado, um push que buscaria uma origem remota para a comparação é recusado antes de buscá-la, assim como aggrega pin. A comparação busca cada origem remota que a entidade escreve por completo no cache de artefatos, exatamente como faz a etapa de fixação, e um cache escrito em uma pasta a partir da qual nenhum workspace foi encontrado transformaria essa pasta em um workspace. Assim, quando nada indica uma raiz e nada ancora uma — a partir da pasta em que você executa o push ou, para uma entidade indicada por um caminho absoluto, a partir da própria pasta da entidade —, um push de uma Recipe ou FeatureRecipe com essa origem para antes que a origem seja buscada, incluindo um dry run e --pin-sources, e nomeia a origem, a pasta e as duas soluções: indique seu workspace com --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou dê a essa pasta um .aggrega-config.yaml contendo um bloco workspace:. A comparação não busca nada para os dois tipos de entidade acima, nem para uma cuja origem é local, então cada uma delas é comparada com seu lock e publicada ali como em qualquer outro lugar; e todos os outros tipos não estão sujeitos a um lock e não são recusados por isso. Configuração lista os outros comandos para os quais isso vale.

aggrega push --pin-sources executa essa mesma etapa para você, primeiro. A etapa é executada antes de o bundle ser construído, então o lock que ela escreve está no artefato publicado e o digest publicado o cobre; e ela é executada antes de qualquer outra recusa que julgue a entidade, então o que é julgado é a entidade já fixada. Somente a regra de diretório acima vem antes, porque a etapa escreve o único lock que o diretório contém. Ela escreve os mesmos bytes que aggrega pin escreve, então a recusa acima nunca é disparada nessa execução: o lock que a etapa acabou de escrever registra exatamente aquilo com que a recusa compararia. A chave de workspace pin_sources_at_push torna isso o padrão de todo push, e --pin-sources=false pula a etapa em uma execução, o que traz a recusa de volta. A etapa escreve ao lado da entidade, o que exige um local gravável — e um push sempre tem um, já que publica o documento que você indica.

--dry-run responde da mesma forma que a publicação responderia. Sem --pin-sources, ele recusa uma entidade não fixada exatamente como a publicação faz, então um dry run que relata um bundle é um que essa recusa deixaria passar. Com --pin-sources, a etapa fixa como dry run: ela imprime o lock que escreveria e não escreve nada, e os dados do bundle que se seguem descrevem o diretório como está, sem esse lock — então o digest é o de uma publicação sem ele e, onde o lock seria novo, também o são o tamanho e, para uma entidade que não nomeia mais nada, o media type. A recusa não é disparada, porque a publicação teria fixado primeiro.

Boa prática: uma alteração em uma versão que você já publicou vai para uma nova versão e, em seguida, para um pin. Copie a entidade para um novo diretório de versão, faça a alteração lá, fixe-a e publique essa. A metade disso que o produto impõe é a próxima seção: publicar conteúdo diferente em uma versão já publicada é recusado. A outra metade — não fixar novamente uma versão já publicada depois de editá-la no seu próprio workspace — cabe a você; nada a recusa localmente, porque fixar novamente é legítimo para uma entidade que você não publicou.

Registry, tag e endereçamento por conteúdo

O registry de destino é --registry <ref> quando fornecido; caso contrário, o default_registry do workspace (hub.aggrega.ai por padrão). A tag é o metadata.version da entidade, e o caminho do repositório é derivado do seu tipo e nome, então o lugar onde uma versão publicada chega não depende do diretório a partir do qual ela foi publicada.

Um default_registry pode conter um caminho de repositório, e uma publicação por meio dele chega sob esse caminho. Com default_registry: ghcr.io/acme, o Component core/api-server na versão 1.0.0 é publicado em ghcr.io/acme/component/core/api-server:1.0.0 — o lugar de onde um pull pelo mesmo padrão o busca, então a assinatura anexada aqui é a que esse pull encontra. --registry nomeia um host, e uma publicação direcionada por ele chega a esse host sem caminho. Seja qual for a forma de nomear o destino, o requisito de assinatura e a configuração de assinatura aplicados são os mantidos para o seu host: um caminho nunca seleciona uma política diferente. A grafia de um caminho é descrita em como um host de registry é escrito.

O manifest nomeia o digest dos bytes publicados, e o lockfile registra o digest do que eles contêm. O manifest OCI que um push escreve nomeia o digest do documento ou arquivo compactado publicado, e aggrega pull recusa um download que não corresponde a ele, então bytes alterados entre a publicação e o pull são detectados. O lockfile que um pull escreve registra a entidade por um digest diferente: o digest do seu conteúdo — o caminho e os bytes de cada arquivo, e nada sobre como o arquivo compactado foi comprimido ou quais bits de permissão seus arquivos tinham. É o digest que um pull no próprio workspace do autor registra para a mesma entidade em seu diretório de catálogo, então um autor e cada consumidor de uma publicação registram o mesmo valor, e um build em qualquer um dos lados recusa conteúdo que não corresponde mais a ele. Os dois digests respondem a perguntas diferentes: o do manifest verifica o download, e o do lockfile é a identidade da entidade.

Publicar sobre uma versão existente

Antes de enviar qualquer byte, aggrega push determina o que o registry de destino já contém na referência que está prestes a escrever e compara isso com o conteúdo à sua frente. Três resultados:

  • Nada foi publicado lá ainda — o push prossegue e publica normalmente.
  • O mesmo conteúdo — nada é enviado, e o comando relata a versão como já publicada, então um push repetido ou tentado novamente não é um erro. O que um push anterior deixou sem anexar — a assinatura ou a data de publicação — é anexado agora, conforme descrito em Concluir uma publicação que um push anterior deixou parcial.
  • Conteúdo diferente — o push é interrompido, nomeando o digest já publicado e o que ele teria escrito. Nenhum flag força a passagem.

Uma versão já publicada, portanto, continua designando os bytes publicados sob ela. Conteúdo que mudou é publicado sob um novo metadata.version; aggrega lint --pre-publish responde à próxima pergunta — quanto essa versão deve avançar — classificando a alteração em relação à versão publicada anteriormente.

--dry-run imprime o digest que um push escreveria, ao lado da referência em que o escreveria:

aggrega push (dry-run): <reference>:<tag> (<digest>)

É o digest que o próprio push compara com o que já está publicado, calculado da mesma forma apenas a partir do conteúdo, e imprimi-lo não contata nenhum registry. Assim, o conteúdo à sua frente pode ser confrontado com o digest com que uma versão foi publicada antes que qualquer push seja feito: onde eles diferem em uma versão publicada, o push seria recusado. Com --pin-sources, é o digest do diretório como está, conforme descrito em Fixar antes de publicar.

Concluir uma publicação que um push anterior deixou parcial

Um push escreve primeiro o conteúdo e anexa a assinatura e a data de publicação depois, então um push que falha em um desses anexos — após suas novas tentativas — deixa o conteúdo publicado sem ele e sai com código diferente de zero, nomeando o que não conseguiu anexar. Executar o mesmo push novamente conclui essa publicação. Ele encontra o conteúdo já publicado, imprime a linha Already published:, não envia nada e anexa o que ainda falta à versão, cada item na linha que uma primeira publicação imprime para ele:

  • A assinatura, onde este push assina. Ela é anexada quando a versão não carrega nenhuma assinatura que conte como a desta publicação. Onde sua configuração fixa uma política de confiança para o host do destino — uma public_key ou trusted_identities, ou, para hub.aggrega.ai, a baseline embutida —, uma assinatura conta quando é verificada sob essa política, então uma assinatura que a política não admite nunca é tomada como a própria da publicação. Onde a política não fixa nenhuma das duas, nenhuma assinatura pode ser verificada em relação a ela, então qualquer assinatura que a versão carregue conta e o push só assina uma versão que não carrega nenhuma; julgar pela verificação nesse caso anexaria outra assinatura a cada execução.
  • A data de publicação, onde a regra das datas exige uma — lida da assinatura recém-anexada, ou daquela já contada — e a versão não carrega nenhum referrer published-at. Um push que não assina deve uma data como uma publicação não assinada, independentemente das assinaturas anexadas à versão depois. A data que ele informa é o relógio deste push: o momento em que a publicação foi concluída, que é posterior ao momento em que o conteúdo chegou pela primeira vez, já que nada do que o registry serve registra esse momento.

Uma publicação já completa não recebe nada anexado, não importa quantas vezes o push seja repetido. Antes de anexar qualquer coisa, o push lê quais assinaturas e datas a versão carrega e cria qualquer assinatura que deva. Uma pergunta que ele não consegue responder — uma listagem ou uma assinatura que não consegue ler, ou uma assinatura que não consegue julgar porque a raiz de confiança não pode ser obtida — e uma assinatura que ele não consegue criar saem cada uma com código diferente de zero sem anexar nada, em vez de serem interpretadas como se a versão não carregasse nenhuma.

Quando o registry faz uma gravação falhar

Um push escreve no registry em etapas: o conteúdo — para um Plugin, a entidade e seu .wasm —, depois o manifest que o nomeia, depois a tag de versão, depois a assinatura e a data de publicação ao lado dele. Cada etapa que escreve é tentada novamente quando falha de uma forma em que uma tentativa posterior pode ter sucesso: o registry responde com um erro de servidor (qualquer status 5xx, exceto um 503 que traga Retry-After) ou 408 Request Timeout, ou a conexão expira, é redefinida ou termina no meio de uma resposta. Uma etapa é tentada no máximo três vezes, aguardando meio segundo antes da segunda tentativa e um segundo antes da terceira.

Um registry que pede para desacelerar é aguardado, e isso não consome nenhuma dessas tentativas. Diante de um 429 Too Many Requests, ou de um 503 que traga Retry-After, toda requisição a esse registry — tanto uma leitura quanto uma escrita — aguarda o tempo que o registry pediu e então é enviada de novo, e uma etapa cujo conteúdo foi recusado recomeça como um novo envio, sem um número fixo de tentativas, até que o registry não tenha respondido nada além de “desacelere” por cinco minutos. Um registry que pede para desacelerar descreve a espera e a recusa que a encerra.

Cada tentativa é um novo envio dos mesmos bytes, nunca um reenvio da requisição que falhou. Um registry que já recebeu o corpo de um envio pode recusar a mesma requisição uma segunda vez, e o que ele aceita é um novo envio. Conteúdo que o registry já contém conta como enviado, e uma etapa tentada novamente escreve o que a primeira tentativa teria escrito, então uma tentativa que chegou mas cuja resposta se perdeu não grava nada duas vezes: o manifest mantém seu digest, e a versão carrega uma única assinatura e uma única data de publicação.

Qualquer outra falha encerra a etapa imediatamente: uma credencial recusada (401, 403 ou nenhuma credencial armazenada para o registry), qualquer outra resposta do registry, um registry totalmente inacessível ou um push que você interrompe. Uma etapa que ainda falha após sua última tentativa faz o comando falhar, e o erro nomeia a etapa — o conteúdo, o manifest, a tag, a assinatura ou a data de publicação. O que as etapas anteriores publicaram continua publicado; Assinatura e A data de publicação explicam o que isso significa para a versão.

Somente as escritas são tentadas novamente nessas falhas. A leitura do que o registry já contém na versão, antes de qualquer envio, não, embora, como toda requisição, aguarde o tempo indicado por um registry que pede para desacelerar.

Assinatura

aggrega push pode assinar o artefato ao publicá-lo e anexar a assinatura como um referrer OCI — um bundle Sigstore (compatível com cosign) sobre o digest imutável do manifest do artefato. A assinatura é um manifest irmão, então assinar nunca reenvia nem altera os bytes publicados. O referrer nomeia seu bundle signature.json, então um cliente OCI genérico que baixa o referrer pelo seu digest grava o bundle nesse arquivo.

A assinatura é sign-before-push: o digest do manifest é conhecido antes da publicação, então aggrega push constrói o assinante e assina o digest antes que qualquer byte chegue ao registry. Se o assinante não puder ser construído ou a assinatura falhar, o push é recusado antes que qualquer coisa seja enviada — nada é publicado, então uma assinatura com falha nunca deixa conteúdo não assinado no registry. Antes de recusar, uma chamada de assinatura que falhou de forma transitória — qualquer falha para a qual uma escrita no registry é tentada novamente, ou a autoridade certificadora keyless informando que não conseguiu processar o token de identidade — é tentada novamente, em até três tentativas com as mesmas esperas. Dentro de uma chamada de 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 é primeiro enviada de novo a esse serviço, como descreve aggrega sign.

A assinatura é anexada depois que o conteúdo chega, então um anexo com falha de fato deixa o conteúdo publicado sem ela. O anexo é uma escrita, tentada novamente conforme descrito em Quando o registry falha em uma escrita. Se ainda falhar, o comando sai com código diferente de zero nomeando a assinatura que não conseguiu anexar, e um consumidor cujo registry exige assinaturas recusa a versão até que uma assinatura seja anexada. Executar o mesmo push novamente a anexa, conforme descrito em Concluir uma publicação que um push anterior deixou parcial; aggrega sign anexa uma à versão publicada por referência.

Uma publicação exige uma assinatura quando o bloco signing próprio do registry de destino define required: true, ou quando o bloco signing de nível superior o faz para todo registry — cada um limitado aos tipos que seu kinds lista, quando lista algum. Essa publicação assina por padrão, e --sign solicita a assinatura explicitamente. Não há flag para fazer push de conteúdo não assinado onde uma assinatura é exigida — esse push sempre é interrompido.

Dois modos de assinatura:

  • Keyless (padrão) — uma chave efêmera vinculada a uma identidade OIDC por um certificado Fulcio de curta duração, registrada no log de transparência Rekor. Fulcio e Rekor usam por padrão as instâncias públicas do Sigstore (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). O carimbo de data/hora confiável keyless vem da inclusão no log de transparência do Rekor; uma autoridade de carimbo de data/hora RFC3161 separada é opcional — forneça --timestamp-url com um endpoint completo para habilitar uma. Em um terminal interativo, a assinatura keyless não precisa de flags: a CLI abre um navegador para obter um token de identidade OIDC de curta duração. No GitHub Actions também não precisa: a CLI gera o token OIDC do workflow automaticamente a partir do endpoint de ambiente do runner. Para outros usos não interativos / CI, exporte AGGREGA_IDENTITY_TOKEN (ou SIGSTORE_ID_TOKEN), ou passe --identity-token; sem token fornecido, sem endpoint de ambiente e sem terminal, o push é recusado. Veja environment-variables.md para o modelo de tokens em CI.
  • Keyed (--key) — uma chave ECDSA P-256 mantida offline (PEM compatível com cosign), a via de escape para ambientes sem provedor de identidade OIDC. Nenhum provedor de identidade, autoridade certificadora ou log de transparência é contatado.

As URLs dos serviços keyless e o caminho da chave keyed também podem ser definidos em .aggrega-config.yaml sob um bloco signing: (global e por registry); um flag substitui a configuração, e a configuração substitui o padrão público. O token de identidade OIDC nunca é um campo de configuração (é um segredo de curta duração), e a chave privada nunca fica inline na configuração — apenas um caminho para ela.

A data de publicação

O horário de criação do manifest é fixado, então o digest de um manifest depende apenas do que é publicado e nunca de quando. A data em que uma versão foi publicada viaja, em vez disso, ao lado dela, e sua origem depende da assinatura:

  • Uma assinatura keyless já a carrega. Sua entrada no log de transparência registra quando o log integrou a assinatura, e a promessa assinada do log atesta esse horário. aggrega push não escreve mais nada.
  • Uma assinatura keyed, ou nenhuma assinatura, não carrega horário. Então, depois que a entidade e qualquer assinatura chegam, aggrega push anexa ao manifest um pequeno referrer published-at — chamado published-at.json para um cliente OCI genérico — contendo um carimbo de data/hora RFC 3339 em UTC com precisão de segundos, lido do próprio relógio da máquina que publica. Ele não é assinado: é a declaração do publicador, e um leitor o registra como tal. A linha Publication date attached: o informa.

Como uma assinatura, o referrer published-at é um manifest irmão que aponta de volta para o publicado, então ele não move nenhum digest nem altera nenhuma tag, e a verificação ao publicar sobre uma versão existente não é afetada por ele. Um push repetido do mesmo conteúdo anexa uma data somente a uma versão que não carrega nenhuma, informando seu próprio relógio — veja Concluir uma publicação que um push anterior deixou parcial. A data é lida do relógio uma única vez, antes da primeira tentativa de anexo, então um anexo tentado novamente — veja Quando o registry falha em uma escrita — informa a mesma data. Um push que publicou seu conteúdo mas não conseguiu anexar a data após essas tentativas sai com código diferente de zero e nomeia o que não foi anexado. aggrega registry update registra a data de cada versão junto com qual das duas fontes a forneceu.

Offline

Publicar é uma ida e volta pela rede e não tem nenhuma forma que não seja, então, no modo offline — a chave de nível superior offline em um arquivo de configuração, AGGREGA_OFFLINE ou --offline —, aggrega push recusa antes de ler sua entidade. A recusa nomeia qual dessas três fontes definiu o modo, que é o que um leitor precisa quando foi a configuração versionada de um projeto que o ativou, e não algo que ele digitou.

--dry-run é a exceção, e é uma exceção por causa do que faz: ele calcula o bundle, imprime a referência que publicaria e o digest que essa publicação produziria, e nunca contata o registry. Isso o torna a forma de publicar segura offline, em vez de um conflito com o modo, e ele continua funcionando nele — com uma ressalva. Para uma Recipe ou FeatureRecipe cujo source: remoto está escrito por completo, essa origem é buscada para comparar seu pin, e no modo offline essa busca é recusada com sua própria mensagem, então um dry run sobre essa entidade para ali em vez de relatar um bundle pelo qual não pode responder.

Para publicar em uma execução a partir de um workspace cuja configuração é offline, passe --offline=false.

Variáveis de ambiente

As entradas de assinatura e o registry de destino podem ser fornecidos pelo ambiente, substituindo .aggrega-config.yaml, enquanto um flag ainda prevalece:

  • AGGREGA_IDENTITY_TOKEN — o token de identidade OIDC keyless (o equivalente em variável de ambiente de --identity-token). SIGSTORE_ID_TOKEN é aceito como alias de interoperabilidade do ecossistema sigstore, com prioridade abaixo de AGGREGA_IDENTITY_TOKEN e do endpoint de ambiente do GitHub Actions. O token nunca é um campo de configuração.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — as URLs dos serviços keyless.
  • AGGREGA_SIGNING_KEY_PATH — um caminho que aponta para um PEM de chave keyed (nunca o material da chave).
  • AGGREGA_DEFAULT_REGISTRY — o registry de destino quando --registry é omitido.

A precedência é flag > ambiente > configuração > padrão. Veja environment-variables.md para a lista completa e o modelo de precedência.

Autenticação

aggrega push lê as credenciais de registry como aggrega pull faz — da configuração de credenciais do Docker e dos credential helpers que ela nomeia. Execute aggrega login <registry>, que não precisa de nenhuma outra ferramenta, ou docker login <registry> antes de fazer push para um registry privado. Veja aggrega-pull.md para saber onde essa configuração é lida.

Veja também

  • ./aggrega-sign.md — assina posteriormente um artefato já publicado (o equivalente pós-publicação de --sign).
  • ./aggrega-lint.md — o controle de publicação (--pre-publish) que deve preceder um push.
  • ./aggrega-pull.md — o lado consumidor, que resolve e fixa o que push publica.
  • ./aggrega-serve.md — o daemon oferece essa mesma publicação em aggrega/publishEntity, para que um editor possa executá-la sem sair da sessão; ela só é executada quando uma requisição a nomeia, e responde com a referência, o digest publicado — em um dry run, o digest que --dry-run imprime —, até onde a chamada chegou e as entradas sobre as quais este comando avisa, como windowsUnusableEntries.
  • ./aggrega-mcp.md — a mesma capacidade como a ferramenta publish-entity, que um assistente pode chamar e que responde com essas entradas como windows_unusable_entries. Leia o que essa página diz sobre permiti-la antes de fazê-lo.
  • ../../architecture/13-catalog-and-registry.md — o modelo de catálogo, registry e mediatypes OCI.

Sinopse

aggrega push <entity-path> [flags]

Descrição

Publish a single catalog entity to an OCI registry, where other workspaces
resolve 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 path
lowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Plugin
its metadata.pluginType, as a segment between <kind> and <metadata.name>. The
tag is the entity's own metadata.version. Run "aggrega push --list-kinds" for
the kinds this binary publishes, one per line and nothing else, so a script can
read it directly. Release and Manifest are deployment-side inputs rather than
catalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: an
entity 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 it
before it is bundled, and one that read refuses is refused here for the same
reason: a document that fails its kind's schema, a path naming content outside
the entity's own directory, which would not travel with the entity, or a schema
a 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 a
metadata.version that is not a semantic version is refused. Its .wasm must then
agree with the entity on what the plugin offers and on its version, and a .wasm
whose 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 build
from uncommitted changes are both cleared by building the plugin from a clean
checkout of the commit its release tag names, never by copying the version it
reports into the entity. A development version such as 1.0.0-3-g1a2b3c4, built
from 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 names
beside 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 Feature
imports — and nothing else in its directory. An entity that names nothing
publishes as its document, unchanged; one that names a file publishes as a
gzipped archive of the document and those files. A directory it names travels
with 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 link
among those files is refused rather than followed. A local source written as a
template names no one directory until a Release fills it in, so an entity with
one 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 Windows
cannot 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 a
part ending in a full stop or a space. On Windows, aggrega refuses to unpack
such a file, so a Windows workspace cannot use the version. The warning is
written to standard error on every platform, one line per file, the entity
document'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 entity
that names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the execute
bit included — in the checkout it is published from. The OCI manifest names the
digest of the published bytes, so "aggrega pull" refuses a download that does
not match it. The lockfile a pull writes records the entity by the digest of its
content — each file's path and its bytes — which is the digest a pull in the
author's own workspace records for the same entity in its catalog directory, so
a build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is made
over the manifest digest before any bytes reach the registry, so a failed
signing refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what is
published and never on when. Push states when it published beside the manifest
instead, as a small published-at attachment carrying this machine's clock, in
UTC to the second — unless the signature it attached already carries a time a
transparency log attests, as a keyless signature does. So a keyed or unsigned
publication writes one, and a keyless one does not. The attachment moves no
digest and changes no tag. "aggrega registry update" records the date, with
which 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.lock
beside 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 is
missing 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, to
have push run that same step first, so the lock it writes is part of what is
published; --pin-sources=false skips it for one run.

Flags

FlagPadrãoDescrição
--dry-runfalseCalcula o bundle e imprime a : proposta com o digest que uma publicação produziria, sem contatar o registry. Uma entidade que a publicação recusaria por um pin ausente também é recusada aqui
--entity—Caminho para o YAML da entidade a publicar (alternativamente, passe como argumento posicional)
--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.
--list-kindsfalseLista todos os tipos de entidade que podem ser publicados e sai sem publicar nada. A saída é legível por máquina e seu formato é estável: um tipo por linha, em ordem, sem mais nada.
--pin-sourcesfalseExecuta a etapa de fixação do autor da entidade sobre a entidade antes de empacotá-la, para que o entity.lock que a etapa escreve ao lado dela faça parte do que é publicado, em vez de recusar uma entidade cujo lock não registra seus pins. A mesma etapa que aggrega pin, escrevendo os mesmos bytes. Ela escreve ao lado da entidade, então só é executada onde a entidade tem um local gravável: um documento em um diretório a partir do qual foi lido — o que um push sempre tem, já que publica o documento de entidade que você indica. Substitui pin_sources_at_push do workspace nos dois sentidos: —pin-sources fixa nesta execução e —pin-sources=false não, independentemente do que diz a configuração
--plugin—Caminho para o artefato .wasm local de uma entidade Plugin. Obrigatório ao publicar um Plugin: a publicação envia o artefato .wasm, calcula seu digest de conteúdo e envia a entidade.
--registry—Host do registry de destino (substitui o default_registry do workspace)
--rekor-url—URL do log de transparência Rekor para assinatura sem chave. Quando omitida, a instância pública do Rekor é usada.
--signfalseAssina o artefato publicado e anexa a assinatura como um referrer OCI. Quando omitido, a assinatura segue a política do registry de destino.
--timestamp-url—URL opcional da autoridade de carimbo de tempo RFC3161 para assinatura sem chave.