aggrega push
aggrega push publica uma entidade do catálogo num registo OCI, onde outros espaços de trabalho a podem resolver com aggrega pull.
O que faz
aggrega push lê um único YAML de entidade, empacota-o para transporte e envia-o para <registry>/<kind>/<metadata.name>:<metadata.version>, com o caminho do repositório em minúsculas; uma Recipe ou FeatureRecipe inclui o seu spec.capability, e um Plugin o 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, para que um script o possa ler diretamente. O conjunto abrange os tipos de autoria do catálogo, juntamente com o Aggregate, um módulo reutilizável, e o Plugin, uma referência endereçada por conteúdo a um artefacto WebAssembly que o compilador encaminha e o runtime executa. O Plugin é um artefacto publicável estrutural e não um tipo de autoria do catálogo. A possibilidade de publicação é uma propriedade da entidade, e não da forma como é utilizada: um Aggregate é publicável quer seja depois referenciado como spec.aggregate de nível superior de uma Release, quer esteja aninhado no bloco aggregates: de outro Aggregate. Release e Manifest são entradas do lado da implementação, não artefactos do catálogo, e são rejeitados.
Empacotamento
Um push publica o documento da entidade e os ficheiros que a própria entidade nomeia ao seu lado — e nada mais do seu diretório. Os ficheiros que uma entidade nomeia são:
- para uma Recipe ou FeatureRecipe, o seu
source:local — um diretório viaja com todos os ficheiros sob ele que as regras de exclusão registadas no seuentity.lockmantêm, como descreve Que ficheiros são enviados com uma entidade; cada ficheiro que as suas entradasvaluesMapping:,workload:eartifacts:importam com$import:; e oentity.lockao seu lado; - para um Component ou uma Feature, cada ficheiro de esquema que o seu
spec.schema, um pilar ou um socketusesSchemaimporta com$import:, incluindo todos os ficheiros que um ficheiro importado, por sua vez, importa.
Um Aggregate, um Plugin e os tipos de biblioteca não nomeiam nenhum ficheiro junto do seu documento. Uma nota, um README, os ficheiros de outra entidade ou a saída de um build que estejam no diretório não são publicados, seja qual for o seu nome. Uma ligação simbólica entre os ficheiros que uma entidade nomeia é recusada em vez de seguida — A symbolic link sits among the files an entity carries (Há uma ligação simbólica entre os ficheiros que uma entidade transporta) — e o mesmo acontece a um caminho que uma entidade nomeia através de um diretório que é uma ligação que conduz para fora do diretório da entidade, antes de qualquer empacotamento — A path names content outside the entity’s own directory (Um caminho nomeia conteúdo fora do próprio diretório da entidade).
A forma decorre daí. Uma entidade que não nomeia nada é publicada como o seu documento, inalterado, sob o tipo de media +yaml do seu tipo. Uma que nomeia um ficheiro é publicada como um .tar.gz que contém o documento e esses ficheiros nos seus lugares no diretório, sob o tipo de media +tar+gz do seu tipo. Assim, uma Recipe cujo conteúdo é todo inline é publicada como o seu documento, e um Component cujo esquema é importado de um ficheiro é publicado como um arquivo. Catálogo e registo §6 lista ambos os tipos de media para todos os tipos.
Cada ficheiro num arquivo tem o modo 0644 e nenhum carimbo temporal, sejam quais forem os seus bits de permissão no disco. Um checkout escreve os ficheiros com os seus próprios bits de permissão, e um sistema que não regista bit de execução faz checkout como ficheiro normal daquilo que outro sistema faz checkout como executável, pelo que o arquivo não contém nenhum modo lido do disco: dois checkouts do mesmo commit publicam os mesmos ficheiros, seja qual for o seu umask e em qualquer sistema em que tenham sido feitos, e mudar o bit de execução de um script não altera nada do que é publicado.
Um push avisa sobre cada entrada de um arquivo que o Windows não consegue conter tal como está escrita — um caminho com uma parte com o nome de um dispositivo, como CON, AUX ou NUL, em maiúsculas ou minúsculas e seja qual for a extensão que se siga, como aux/x.yaml, ou uma parte que termina num ponto final ou num espaço, como report.. No Windows, aggrega recusa-se a desempacotar uma entrada destas, pelo que um espaço de trabalho Windows não pode utilizar a versão. O aviso é escrito no erro padrão em todas as plataformas, uma linha por entrada, antes do relato da própria publicação; o próprio nome de ficheiro do documento da entidade é avaliado juntamente com os ficheiros que nomeia, e uma entidade que não nomeia nada é publicada apenas como o seu documento e nunca recebe aviso. Não recusa nada: o push avança 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 publicado contém uma entrada que o Windows não consegue utilizar) mostra a linha e o que fazer.
Um source: local escrito como modelo transporta o diretório inteiro. Um modelo como ./charts/{{ .values.flavour }} só nomeia um diretório quando uma Release o preenche, pelo que nenhuma publicação pode saber qual será. Uma entidade destas transporta todos os ficheiros do seu próprio diretório que as suas regras de exclusão registadas mantêm — nunca o seu .aggregaignore, cujas regras viajam dentro do lock — e o push indica-o por baixo dos seus outros factos:
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 itO que não é nomeado não viaja, e é o consumidor que dá por isso. Um ficheiro de que a entidade depende sem o nomear através de um dos campos acima não está na publicação, e o build de um consumidor falha, nomeando o caminho em falta dentro da sua posição de cache — não o push do autor. Nomeie todos os ficheiros de que a entidade precisa através de um desses campos.
Cada ficheiro publicado é nomeado no manifesto do artefacto, pelo que um cliente OCI genérico como oras o escreve num ficheiro com esse nome: entity.yaml para uma entidade publicada como o seu documento, entity.tar.gz para uma publicada com os seus ficheiros, e, para um Plugin, entity.yaml para a entidade junto de entity.wasm para o seu executável. O nome decorre do tipo de media, e não do ficheiro a partir do qual se publica, pelo que o mesmo conteúdo publicado a partir de um ficheiro renomeado publica o mesmo artefacto. Catálogo e registo §6 lista todas as formas publicadas e o ficheiro em que cada uma fica.
Um URL source: remoto numa Recipe (uma referência de chart OCI, um URL de chart ou fragmento HTTPS, um módulo Git) é preservado literalmente no YAML publicado; não é obtido nem incorporado no artefacto. Os consumidores resolvem e fixam as origens remotas de forma independente, na altura do seu próprio pull. Isto mantém a distribuição de entidades do catálogo e a resolução de artefactos de origem como questões separadas.
Um Aggregate é publicado como o seu próprio documento único: um subagregado que referencia em aggregates: não é incluído no artefacto. Cada subagregado é um Aggregate publicado separadamente que os consumidores resolvem e fixam de forma independente na altura do pull, pela identidade — o mesmo princípio de separação da distribuição que se aplica às origens remotas.
Uma entidade por diretório
Um arquivo contém o ficheiro da entidade entre os ficheiros que nomeia, pelo que a entidade tem de ser encontrada de novo à saída. Um consumidor encontra-a pelo preâmbulo que contém: o documento no topo do pacote cujo kind: é um tipo de entidade publicável é a entidade. O ficheiro em que é escrita pode ter qualquer nome — recipe.yaml é a convenção do catálogo e não um requisito — e um fragmento compose, um modelo de chart ou um manifesto Kubernetes junto da entidade não é confundido com ela, porque esses declaram outra coisa ou nenhum tipo. Os documentos de entidade mais abaixo, dentro de uma árvore source/, são conteúdo que a entidade transporta e não a própria entidade, e nunca são considerados.
Um push recusa uma entidade que partilha o seu diretório com outra entidade. Todos os tipos têm um diretório próprio, exceto Aggregate, Release e Manifest, que a raiz de um espaço de trabalho contém lado a lado. Para qualquer outro tipo, um push verifica, antes de fazer qualquer outra coisa com a entidade — antes do passo de fixação, da política de assinatura e do pacote — que nenhum outro documento de entidade se encontra no mesmo diretório, e recusa caso contrário, nomeando cada entidade que está a mais, quer se tenha pedido ao push que fixasse quer não. aggrega pin recusa o mesmo diretório nas mesmas palavras; a paragem é An entity shares its directory with another entity (Uma entidade partilha o seu diretório com outra entidade). Um documento que não seja de nenhum tipo de entidade junto da entidade — um ficheiro de chart, um fragmento compose, um README — não está a mais, nem nada que esteja num subdiretório. Cada documento junto da entidade só é lido de dentro do espaço de trabalho ou, para uma entidade nomeada fora dele, de dentro do próprio diretório da entidade, pelo que um que seja uma ligação para fora faz parar o push nomeando a ligação, sem a ler, como expõe a fronteira do espaço de trabalho.
A regra é o que mantém um entity.lock pertencente a uma única entidade: o nome de ficheiro do lock é o mesmo para todas as entidades, pelo que duas entidades escritas num diretório partilhariam o único lock para que este tem espaço. Só é avaliada quando algo é produzido a partir do diretório, pelo que um diretório que contenha várias entidades continua a ser carregado, analisado pelo lint e compilado.
O nome do diretório não é avaliado. Uma entidade sozinha no seu diretório é publicada no seu metadata.version, onde quer que esse diretório se encontre; <name>/<version>/, a disposição que o catálogo da biblioteca padrão segue, é uma convenção. Um artefacto que outro cliente publicou a partir de um diretório com duas entidades continua a ser lido com segurança: um pull dele para, nomeando ambos os documentos em vez de responder com qualquer um deles, catalogado em errors/fatal-halts.md.
Ler a entidade antes de ser empacotada
Um push lê um Component, uma Feature, uma Recipe ou uma FeatureRecipe como um build os lê, e recusa um que essa leitura recuse — pela mesma razão, com o mesmo código curto, antes de o pacote ser construído e antes de o registo de destino ser contactado. Assim, um documento que falhe o esquema do seu tipo, um caminho que nomeie conteúdo fora do próprio diretório da entidade e um esquema que um Component ou uma Feature importe com $import: e que esteja em falta ou não possa 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 nomeia também um ficheiro que não viajaria com a entidade, porque todos os ficheiros que uma publicação transporta são retirados do próprio diretório da entidade — consulte A path names content outside the entity’s own directory (Um caminho nomeia conteúdo fora do próprio diretório da entidade).
Uma Recipe ou FeatureRecipe é lida desta forma quando as suas fixações são comparadas, o que a secção seguinte descreve, pelo que a leitura acontece quer se peça ao push que fixe quer não, e quer a entidade tenha algo para fixar quer não. Cada um dos quatro tipos é também lido desta forma imediatamente antes de o seu pacote ser construído, porque é essa leitura que indica que ficheiros nomeia. Um Aggregate e uma biblioteca não nomeiam nenhum ficheiro e não são lidos desta forma. Um Plugin também não nomeia nenhum ficheiro, e é lido em relação ao esquema do seu tipo antes do seu .wasm, como descreve Publicar um Plugin.
Publicar um Plugin
Um Plugin é publicado juntamente com o seu .wasm, nomeado por --plugin, e um push avalia os dois antes de qualquer byte ser publicado ou de o registo ser contactado. --dry-run avalia-os exatamente como uma publicação.
A entidade é lida primeiro em relação ao esquema do seu tipo, como um carregamento do catálogo a lê, antes de o .wasm ser lido. Assim, um metadata.version que não seja uma versão semântica — um commit simples como 415148e — é recusado com a própria condição do esquema, nomeando o campo, e o mesmo acontece a qualquer outro desvio em relação ao esquema, como um spec.abiVersion em falta. O que conta aqui como versão semântica é o próprio padrão do esquema para metadata.version; o push não acrescenta nenhuma regra própria.
Depois, o .wasm é carregado e comparado com a entidade. O que reporta oferecer tem de concordar com o que a entidade afirma, o conjunto de comandos e as funções de anfitrião que a entidade regista têm de lhe corresponder, e a versão que reporta sobre o seu próprio build tem de ser igual a metadata.version — consulte A Plugin entity’s recorded version does not match the plugin (A versão registada de uma entidade Plugin não corresponde ao plugin).
Um .wasm compilado a partir de uma árvore de trabalho com alterações não submetidas é recusado. Um build destes tem a marca -dirty no fim da versão que reporta — 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, pelo que ninguém poderia recompilar o que foi publicado a partir da versão sob a qual foi publicado. O push recusa-o, nomeando a versão e a reparação: compilar o plugin a partir de um checkout limpo do commit que a tag da versão nomeia, para que reporte a própria versão de lançamento — e, para lançar a alteração, submetê-la com o metadata.version da entidade definido para o novo lançamento e marcar primeiro esse commit com a tag — em vez de copiar para a entidade a versão que uma recompilação reporta. 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 submetidas).
Fixar antes de publicar
Uma Recipe ou FeatureRecipe contém as fixações das entradas que lê — um source: remoto escrito por extenso, um ficheiro que uma entrada artifacts importa, os ficheiros de um source: ao seu lado — no entity.lock ao seu lado, e um push publica esse ficheiro com a entidade. Fixar é um passo executado antes de publicar, aggrega pin, e o lock que escreve deve ser submetido.
Um push recusa uma entidade cujo lock não regista essas fixações. Antes de construir o pacote, um push determina o que o passo de fixação registaria para a entidade e compara-o com o entity.lock ao seu lado. Onde falta uma fixação, ou o lock contém uma a que uma entrada já não corresponde, o push para antes de qualquer arquivo ser construído ou de qualquer registo ser contactado. 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 sobre a entidade, --pin-sources no push acabado de executar, ou pin_sources_at_push para todos os pushes do espaço de trabalho. É 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 seu lado não regista fixação), com as soluções próprias de um push. Assim, uma Recipe ou FeatureRecipe que um push publica transporta, dentro do seu pacote, um lock que regista todas as fixações que o passo teria registado no momento em que foi publicada.
Dois tipos de entidade não têm nada para fixar e são publicados sem alterações: uma entidade que não lê nenhuma origem remota, não importa nenhum ficheiro e não nomeia nenhuma origem local, e uma Recipe cujas coordenadas de origem remota são preenchidas a partir de um modelo. Essa origem só nomeia um artefacto quando uma Release preenche o modelo, pelo que a sua fixação pertence ao lockfile de cada Release, e um push não pede nenhuma junto da entidade. Um Component, uma Feature, uma biblioteca, um Aggregate ou um Plugin não leem nada que o lock registe e nunca são recusados aqui.
Comparar a fixação de uma origem remota significa obter a origem, como aggrega pin faz, porque uma fixação que já não corresponde só é visível em relação ao que a origem serve agora. Um push sobre uma entidade com uma origem destas alcança, portanto, o anfitrião da origem antes de alcançar o registo. A comparação lê uma Recipe ou FeatureRecipe como o passo de fixação a lê, através do catálogo, pelo que uma que o catálogo se recuse a ler — um documento que falhe o esquema do seu tipo, por exemplo — é recusada aqui com a própria razão do catálogo.
Onde não foi encontrado nem nomeado nenhum espaço de trabalho, um push que obteria uma origem remota para a comparação é recusado antes de a obter, tal como aggrega pin. A comparação obtém cada origem remota que a entidade escreve por extenso para a cache de artefactos, exatamente como o passo de fixação, e uma cache escrita numa pasta a partir da qual não foi encontrado nenhum espaço de trabalho tornaria essa pasta um espaço de trabalho. Assim, quando nada nomeia uma raiz e nada ancora uma — a partir da pasta onde o push é executado ou, para uma entidade nomeada por um caminho absoluto, a partir da própria pasta da entidade — um push de uma Recipe ou FeatureRecipe com uma origem destas para antes de a origem ser obtida, incluindo uma execução de teste e --pin-sources, e nomeia a origem, a pasta e as duas saídas possíveis: nomear o espaço de trabalho com --workspace-root ou AGGREGA_WORKSPACE_ROOT, ou dar a essa pasta um .aggrega-config.yaml com um bloco workspace:. A comparação não obtém nada para os dois tipos de entidade acima, nem para uma cuja origem é local, pelo que cada uma delas é comparada com o seu lock e publicada aí como em qualquer outro sítio; e todos os outros tipos não são vinculados a um lock e não são recusados por isto. Configuração lista os outros comandos a que isto se aplica.
aggrega push --pin-sources executa primeiro esse mesmo passo pelo utilizador. O passo é executado antes de o pacote ser construído, pelo que o lock que escreve está no artefacto publicado e o digest publicado abrange-o; e é executado antes de qualquer outra recusa que avalie a entidade, pelo que o que é avaliado é a entidade tal como fixada. Só a regra do diretório acima vem primeiro, porque o passo escreve o único lock que o diretório contém. Escreve os mesmos bytes que aggrega pin escreve, pelo que a recusa acima nunca dispara nessa execução: o lock que o passo acabou de escrever regista exatamente aquilo com que a recusa compararia. A chave de espaço de trabalho pin_sources_at_push torna isto a predefinição de todos os pushes, e --pin-sources=false salta o passo numa execução, o que traz de volta a recusa. O passo escreve junto da entidade, o que exige um local gravável — e um push tem sempre um, já que publica o documento que o utilizador nomeia.
--dry-run responde como a publicação responderia. Sem --pin-sources, recusa uma entidade não fixada exatamente como a publicação, pelo que uma execução de teste que reporta um pacote é uma que esta recusa deixaria passar. Com --pin-sources, o passo fixa em modo de teste: imprime o lock que escreveria e não escreve nada, e os factos do pacote que se seguem descrevem o diretório tal como está, sem esse lock — pelo que 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 tipo de media. A recusa não dispara, porque a publicação teria fixado primeiro.
Boa prática: uma alteração a uma versão já publicada vai para uma nova versão, seguida de uma fixação. Copie a entidade para um novo diretório de versão, faça aí a alteração, fixe-a e publique-a. A metade disto que o produto impõe é a secção seguinte: publicar conteúdo diferente numa versão já publicada é recusado. A outra metade — não voltar a fixar uma versão já publicada depois de a editar no próprio espaço de trabalho — cabe ao utilizador; nada a recusa localmente, porque voltar a fixar é legítimo para uma entidade ainda não publicada.
Registo, tag e endereçamento por conteúdo
O registo de destino é --registry <ref> quando fornecido, caso contrário o default_registry do espaço de trabalho (hub.aggrega.ai por predefinição). A tag é o metadata.version da entidade, e o caminho do repositório deriva do seu tipo e nome, pelo que o local onde uma versão publicada fica não depende do diretório a partir do qual foi publicada.
Um default_registry pode incluir um caminho de repositório, e uma publicação através dele fica 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 local de onde um pull através do mesmo predefinido o obtém, pelo que a assinatura aqui anexada é a que esse pull encontra. --registry nomeia um anfitrião, e uma publicação que ele dirige fica nesse anfitrião sem caminho. Seja qual for a forma como o destino é nomeado, o requisito de assinatura e a configuração de assinatura aplicáveis são os guardados para o seu anfitrião: um caminho nunca seleciona uma política diferente. A grafia de um caminho é explicada em como se escreve um anfitrião de registo.
O manifesto nomeia o digest dos bytes publicados, e o lockfile regista o digest do que estes transportam. O manifesto OCI que um push escreve nomeia o digest do documento ou arquivo publicado, e aggrega pull recusa uma transferência que não lhe corresponda, pelo que bytes alterados entre a publicação e o pull são detetados. O lockfile que um pull escreve regista a entidade por um digest diferente: o digest do seu conteúdo — o caminho e os bytes de cada ficheiro, e nada sobre a forma como o arquivo foi comprimido ou os bits de permissão que os seus ficheiros tinham. Esse é o digest que um pull no próprio espaço de trabalho do autor regista para a mesma entidade no seu diretório de catálogo, pelo que um autor e todos os consumidores de uma publicação registam o mesmo valor, e um build de qualquer dos lados recusa conteúdo que já não lhe corresponda. Os dois digests respondem a perguntas diferentes: o do manifesto verifica a transferência, e o do lockfile é a identidade da entidade.
Publicar sobre uma versão existente
Antes de qualquer byte ser enviado, aggrega push resolve o que o registo de destino já contém na referência que está prestes a escrever e compara-o com o conteúdo que tem à frente. Três resultados:
- Ainda não há nada publicado ali — o push avança e publica normalmente.
- O mesmo conteúdo — nada é enviado, e o comando reporta a versão como já publicada, pelo que um push repetido ou tentado de novo não é um erro. O que um push anterior deixou por anexar — a assinatura, ou a data de publicação — é anexado agora, como descreve Concluir uma publicação que um push anterior deixou parcial.
- Conteúdo diferente — o push para, nomeando o digest já publicado e o que teria escrito. Nenhuma opção o força a passar.
Uma versão já publicada continua, portanto, a designar os bytes publicados sob ela. O conteúdo que mudou é publicado sob um novo metadata.version; aggrega lint --pre-publish responde à pergunta seguinte — quanto deve essa versão avançar — classificando a alteração em relação à versão publicada anteriormente.
--dry-run imprime o digest que um push escreveria, junto 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 contacta nenhum registo. Assim, o conteúdo que se tem à frente pode ser comparado com o digest com que uma versão foi publicada antes de qualquer push: onde diferem numa versão publicada, o push seria recusado. Com --pin-sources, é o digest do diretório tal como está, como descreve Fixar antes de publicar.
Concluir uma publicação que um push anterior deixou parcial
Um push escreve primeiro o conteúdo e anexa depois a assinatura e a data de publicação, pelo que um push que falhe num desses anexos — depois das suas novas tentativas — deixa o conteúdo publicado sem ele e termina com código diferente de zero, nomeando o que não conseguiu anexar. Executar novamente o mesmo push conclui essa publicação. Encontra o conteúdo já publicado, imprime a linha Already published:, não envia nada e anexa o que ainda falta à versão, cada coisa na linha que uma primeira publicação imprime para ela:
- A assinatura, onde este push assina. É anexada quando a versão não tem nenhuma assinatura que conte como a desta publicação. Onde a configuração fixa uma política de confiança para o anfitrião do destino — uma
public_keyoutrusted_identities, ou, parahub.aggrega.ai, a base incorporada — uma assinatura conta quando é verificada segundo essa política, pelo que uma assinatura que a política não admite nunca é tomada como a da própria publicação. Onde a política não fixa nenhuma das duas, nenhuma assinatura pode ser verificada em relação a ela, pelo que qualquer assinatura que a versão tenha conta e o push só assina uma versão que não tenha nenhuma; avaliar por verificação nesse caso anexaria outra assinatura em cada execução. - A data de publicação, onde a regra das datas exige uma — lida da assinatura acabada de anexar, ou da que já foi contada — e a versão não tem nenhum referrer published-at. Um push que não assina deve uma data tal como uma publicação não assinada, sejam quais forem as assinaturas anexadas à versão depois. A data que indica é o relógio deste push: a hora em que a publicação foi concluída, que é posterior à hora em que o conteúdo foi depositado pela primeira vez, já que nada do que o registo serve regista esse momento.
Uma publicação já completa não recebe nada, por muitas vezes que o push seja repetido. Antes de anexar o que quer que seja, o push lê que assinaturas e datas a versão tem e faz qualquer assinatura que deva. Uma pergunta a que não consegue responder — uma listagem ou uma assinatura que não consegue ler, ou uma assinatura que não consegue avaliar porque a raiz de confiança não pode ser obtida — e uma assinatura que não consegue fazer terminam cada uma com código diferente de zero sem nada anexado, em vez de serem tomadas como indicação de que a versão não tem nenhuma.
Quando o registo falha uma escrita
Um push escreve no registo por passos: o conteúdo — para um Plugin, a entidade e o seu .wasm — depois o manifesto que o nomeia, depois a tag da versão e depois a assinatura e a data de publicação ao seu lado. Cada passo que escreve é repetido quando falha de uma forma em que uma tentativa posterior pode ter êxito: o registo responde com um erro de servidor (qualquer estado 5xx, exceto um 503 que traga Retry-After) ou 408 Request Timeout, ou a ligação esgota o tempo limite, é reposta ou termina a meio de uma resposta. Um passo é tentado no máximo três vezes, esperando meio segundo antes da segunda tentativa e um segundo antes da terceira.
Um registo que pede para abrandar é aguardado, e isso não gasta nenhuma dessas tentativas. Perante um 429 Too Many Requests, ou um 503 que traga Retry-After, cada pedido a esse registo — tanto uma leitura como uma escrita — espera o tempo que o registo pediu e depois é enviado de novo, e um passo cujo conteúdo foi recusado recomeça como um novo envio, sem um número fixo de tentativas, até o registo não ter respondido mais nada além de «abrande» durante cinco minutos. Um registo que pede para abrandar descreve a espera e a recusa que lhe põe fim.
Cada tentativa é um novo envio dos mesmos bytes, nunca um reenvio do pedido que falhou. Um registo que já recebeu o corpo de um envio pode recusar o mesmo pedido uma segunda vez, e um novo envio é o que aceita. O conteúdo que o registo já contém conta como enviado, e um passo repetido escreve o que a primeira tentativa teria escrito, pelo que uma tentativa que foi depositada mas cuja resposta se perdeu não deposita nada duas vezes: o manifesto mantém o seu digest, e a versão tem uma única assinatura e uma única data de publicação.
Todas as outras falhas terminam o passo de imediato: uma credencial recusada (401, 403, ou nenhuma credencial guardada para o registo), qualquer outra resposta que o registo dê, um registo que não está de todo acessível, ou um push interrompido pelo utilizador. Um passo que continue a falhar depois da sua última tentativa faz falhar o comando, e o erro nomeia o passo — o conteúdo, o manifesto, a tag, a assinatura ou a data de publicação. O que os passos anteriores publicaram continua publicado; Assinatura e A data de publicação explicam o que isso significa para a versão.
Só as escritas são repetidas perante essas falhas. Ler o que o registo já contém na versão, antes de qualquer envio, não é, embora, como qualquer pedido, espere o tempo indicado por um registo que pede para abrandar.
Assinatura
aggrega push pode assinar o artefacto ao publicá-lo e anexar a assinatura como um referrer OCI — um pacote Sigstore (compatível com cosign) sobre o digest imutável do manifesto do artefacto. A assinatura é um manifesto irmão, pelo que assinar nunca volta a enviar nem altera os bytes publicados. O referrer nomeia o seu pacote signature.json, pelo que um cliente OCI genérico que obtenha o referrer pelo seu digest escreve o pacote nesse ficheiro.
A assinatura é assinar-antes-de-enviar: o digest do manifesto é conhecido antes da publicação, pelo que aggrega push constrói o signatário e assina o digest antes de qualquer byte chegar ao registo. Se o signatário não puder ser construído ou a assinatura falhar, o push é recusado antes de qualquer envio — nada é publicado, pelo que uma assinatura falhada nunca deixa conteúdo não assinado no registo. Antes de recusar, uma chamada de assinatura que falhou transitoriamente — qualquer falha pela qual uma escrita no registo é repetida, ou a autoridade de certificação keyless a reportar que não conseguiu processar o token de identidade — é tentada de novo, até três tentativas com as mesmas esperas. Dentro de uma chamada de 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 é primeiro reenviado a esse serviço, como descreve aggrega sign.
A assinatura é anexada depois de o conteúdo ser depositado, pelo que um anexo falhado deixa de facto o conteúdo publicado sem ela. O anexo é uma escrita, repetida como descreve Quando o registo faz falhar uma escrita. Se continuar a falhar, o comando termina com código diferente de zero nomeando a assinatura que não conseguiu anexar, e um consumidor cujo registo exige assinaturas recusa a versão até ser anexada uma assinatura. Executar novamente o mesmo push anexa-a, como descreve 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 registo de destino define required: true, ou quando o bloco signing de nível superior o faz para todos os registos — cada um limitado aos tipos que o seu kinds lista, quando lista algum. Uma publicação destas assina por predefinição, e --sign pede explicitamente a assinatura. Não há nenhuma opção para enviar conteúdo não assinado onde é exigida uma assinatura — esse push para sempre.
Dois modos de assinatura:
- Keyless (predefinição) — uma chave efémera associada a uma identidade OIDC por um certificado Fulcio de curta duração, registado no registo de transparência Rekor. Fulcio e Rekor usam por predefinição as instâncias Sigstore públicas (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). O carimbo temporal de confiança keyless vem da inclusão no registo de transparência do Rekor; uma autoridade de carimbo temporal RFC3161 separada é opcional — forneça--timestamp-urlcom um endpoint completo para ativar uma. Num terminal interativo, a assinatura keyless não precisa de opções: a CLI abre um navegador para adquirir um token de identidade OIDC de curta duração. No GitHub Actions também não precisa de nenhuma: a CLI gera automaticamente o token OIDC do workflow a partir do endpoint ambiente do runner. Para outra utilização não interativa / de CI, exporteAGGREGA_IDENTITY_TOKEN(ouSIGSTORE_ID_TOKEN), ou passe--identity-token; sem token fornecido, sem endpoint ambiente e sem terminal, o push é recusado. Consulte environment-variables.md para o modelo de tokens de CI. - Com chave (
--key) — uma chave ECDSA P-256 detida offline (PEM compatível com cosign), a via de escape para ambientes sem fornecedor de identidade OIDC. Não é contactado nenhum fornecedor de identidade, autoridade de certificação ou registo de transparência.
Os URLs dos serviços keyless e o caminho da chave para assinatura com chave também podem ser definidos em .aggrega-config.yaml, sob um bloco signing: (global e por registo); uma opção substitui a configuração, e a configuração substitui a predefinição pública. O token de identidade OIDC nunca é um campo de configuração (é um segredo de curta duração), e a chave privada nunca está inline na configuração — apenas um caminho para ela.
A data de publicação
A hora de criação do manifesto é fixada, pelo que o digest de um manifesto depende apenas do que é publicado e nunca de quando. A data em que uma versão foi publicada viaja, em vez disso, ao seu lado, e a sua proveniência depende da assinatura:
- Uma assinatura keyless já a contém. A sua entrada no registo de transparência regista quando o registo integrou a assinatura, e a promessa assinada do registo atesta essa hora.
aggrega pushnão escreve mais nada. - Uma assinatura com chave, ou nenhuma assinatura, não contém nenhuma hora. Por isso, depois de a entidade e qualquer assinatura terem sido depositadas,
aggrega pushanexa ao manifesto um pequeno referrer published-at — chamadopublished-at.jsonpara um cliente OCI genérico — que contém um carimbo temporal RFC 3339 em UTC ao segundo, lido do próprio relógio da máquina que publica. Não é assinado: é a declaração do publicador, e um leitor regista-o como tal. A linhaPublication date attached:reporta-o.
Tal como uma assinatura, o referrer published-at é um manifesto irmão que aponta de volta para o publicado, pelo que 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 só anexa uma data a uma versão que não tenha nenhuma, indicando o seu próprio relógio — consulte 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, pelo que um anexo repetido — consulte Quando o registo faz falhar uma escrita — indica a mesma data. Um push que publicou o seu conteúdo mas não conseguiu anexar a data depois dessas tentativas termina com código diferente de zero e nomeia o que não foi anexado. aggrega registry update regista a data de cada versão juntamente com a fonte, das duas, de onde veio.
Offline
Publicar é uma ida e volta pela rede e não tem nenhuma forma que não o seja, pelo que, sob a postura offline — a chave de nível superior offline num ficheiro de configuração, AGGREGA_OFFLINE, ou --offline — aggrega push recusa antes de ler a entidade. A recusa nomeia qual desses três definiu a postura, que é o que um leitor precisa quando foi a configuração submetida de um projeto que a ativou, e não algo que tenha escrito.
--dry-run é a exceção, e é uma exceção por causa do que faz: calcula o pacote, imprime a referência que publicaria e o digest que essa publicação depositaria, e nunca contacta o registo. Isso torna-o a forma de publicação segura offline, e não um conflito com a postura, e continua a funcionar sob ela — com uma ressalva. Uma Recipe ou FeatureRecipe cujo source: remoto está escrito por extenso tem essa origem obtida para comparar a sua fixação, e sob a postura offline essa obtenção é recusada nos seus próprios termos, pelo que uma execução de teste sobre uma entidade destas para aí em vez de reportar um pacote que não pode garantir.
Para publicar numa execução a partir de um espaço de trabalho cuja configuração é offline, passe --offline=false.
Variáveis de ambiente
As entradas de assinatura e o registo de destino podem ser fornecidos através do ambiente, substituindo .aggrega-config.yaml, embora uma opção continue a prevalecer:
AGGREGA_IDENTITY_TOKEN— o token de identidade OIDC keyless (a contrapartida em ambiente de--identity-token).SIGSTORE_ID_TOKENé respeitado como alias de interoperabilidade do ecossistema sigstore, com prioridade abaixo deAGGREGA_IDENTITY_TOKENe do endpoint ambiente do GitHub Actions. O token nunca é um campo de configuração.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— os URLs dos serviços keyless.AGGREGA_SIGNING_KEY_PATH— um ponteiro de caminho para um PEM de chave para assinatura com chave (nunca material de chave).AGGREGA_DEFAULT_REGISTRY— o registo de destino quando--registryé omitido.
A precedência é opção > ambiente > configuração > predefinição. Consulte environment-variables.md para a lista completa e o modelo de precedência.
Autenticação
aggrega push lê as credenciais de registo tal como aggrega pull — a partir da configuração de credenciais do Docker e dos auxiliares de credenciais que esta nomeia. Execute aggrega login <registry>, que não precisa de nenhuma outra ferramenta, ou docker login <registry> antes de enviar para um registo privado. Consulte aggrega-pull.md para saber onde essa configuração é lida.
Ver também
- ./aggrega-sign.md — assinar posteriormente um artefacto já publicado (a contrapartida pós-publicação de
--sign). - ./aggrega-lint.md — a verificação de publicação (
--pre-publish) que deve preceder um push. - ./aggrega-pull.md — o lado consumidor, que resolve e fixa o que
pushpublica. - ./aggrega-serve.md — o daemon disponibiliza esta mesma publicação em
aggrega/publishEntity, para que um editor a possa executar sem sair da sessão; só é executada quando um pedido a nomeia, e responde com a referência, o digest publicado — numa execução de teste, o digest que--dry-runimprime — até onde a chamada chegou e as entradas sobre as quais este comando avisa, comowindowsUnusableEntries. - ./aggrega-mcp.md — a mesma capacidade, na forma da ferramenta
publish-entity, que um assistente pode chamar, respondendo com essas entradas comowindows_unusable_entries. Leia o que essa página diz sobre a permitir antes de o fazer. - ../../architecture/13-catalog-and-registry.md — o modelo de catálogo, registo e tipos de media OCI.
Sinopse
aggrega push <entity-path> [flags]Descrição
Publish a single catalog entity to an OCI registry, where other workspacesresolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to<registry>/<kind>/<metadata.name>:<metadata.version>, the repository pathlowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Pluginits metadata.pluginType, as a segment between <kind> and <metadata.name>. Thetag is the entity's own metadata.version. Run "aggrega push --list-kinds" forthe kinds this binary publishes, one per line and nothing else, so a script canread it directly. Release and Manifest are deployment-side inputs rather thancatalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: anentity of any other kind is refused when another entity sits in its directory,before anything is pinned or bundled, and the refusal names the entity in the way.The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads itbefore it is bundled, and one that read refuses is refused here for the samereason: a document that fails its kind's schema, a path naming content outsidethe entity's own directory, which would not travel with the entity, or a schemaa Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so ametadata.version that is not a semantic version is refused. Its .wasm must thenagree with the entity on what the plugin offers and on its version, and a .wasmwhose version says it was built from a working tree with uncommitted changes —the -dirty mark a build adds — is refused. A version disagreement and a buildfrom uncommitted changes are both cleared by building the plugin from a cleancheckout of the commit its release tag names, never by copying the version itreports into the entity. A development version such as 1.0.0-3-g1a2b3c4, builtfrom a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself namesbeside it — a Recipe's or FeatureRecipe's local source, each file an $import:names, the entity.lock beside it, and each schema file a Component or Featureimports — and nothing else in its directory. An entity that names nothingpublishes as its document, unchanged; one that names a file publishes as agzipped archive of the document and those files. A directory it names travelswith every file under it that the ignore rules recorded in its entity.lock keep:the rules the plugin serving its capability declared, and the author's own.aggregaignore beside it, composed when the entity was pinned. A symbolic linkamong those files is refused rather than followed. A local source written as atemplate names no one directory until a Release fills it in, so an entity withone carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windowscannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or apart ending in a full stop or a space. On Windows, aggrega refuses to unpacksuch a file, so a Windows workspace cannot use the version. The warning iswritten to standard error on every platform, one line per file, the entitydocument's own file name judged with the rest, and it refuses nothing: the push,or its dry run, goes ahead or stops exactly as it would without it. An entitythat names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the executebit included — in the checkout it is published from. The OCI manifest names thedigest of the published bytes, so "aggrega pull" refuses a download that doesnot match it. The lockfile a pull writes records the entity by the digest of itscontent — each file's path and its bytes — which is the digest a pull in theauthor's own workspace records for the same entity in its catalog directory, soa build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is madeover the manifest digest before any bytes reach the registry, so a failedsigning refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what ispublished and never on when. Push states when it published beside the manifestinstead, as a small published-at attachment carrying this machine's clock, inUTC to the second — unless the signature it attached already carries a time atransparency log attests, as a keyless signature does. So a keyed or unsignedpublication writes one, and a keyless one does not. The attachment moves nodigest and changes no tag. "aggrega registry update" records the date, withwhich of the two it came from.
Push refuses to replace content already published at the same version:publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lockbeside it, and pinning them is a step you run before publishing: aggrega pin.A push that does not run that step refuses an entity whose entity.lock ismissing a pin, or holds one an input no longer matches, and names the step.Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, tohave push run that same step first, so the lock it writes is part of what ispublished; --pin-sources=false skips it for one run.Flags
| Flag | Predefinição | Descrição |
|---|---|---|
--dry-run | false | Calcular o pacote e imprimir o |
--entity | — | Caminho para o YAML da entidade a publicar (em alternativa, passe-o como argumento posicional) |
--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. |
--list-kinds | false | Listar todos os tipos de entidade que podem ser publicados e sair sem publicar nada. A saída é legível por máquina e a sua forma é estável: um tipo por linha, por ordem, e nada mais. |
--pin-sources | false | Executar o passo de fixação do autor da entidade sobre a entidade antes de a empacotar, para que o entity.lock que o passo escreve ao seu lado faça parte do que é publicado, em vez de recusar uma entidade cujo lock não regista as suas fixações. O mesmo passo que aggrega pin, escrevendo os mesmos bytes. Escreve junto da entidade, pelo que só é executado onde a entidade tem um local gravável: um documento num diretório de onde foi lido — que um push tem sempre, já que publica o documento de entidade que o utilizador nomeia. Substitui o pin_sources_at_push do espaço de trabalho nos dois sentidos: —pin-sources fixa nesta execução e —pin-sources=false não fixa, diga a definição o que disser |
--plugin | — | Caminho para o artefacto .wasm local de uma entidade Plugin. Obrigatório ao publicar um Plugin: a publicação envia o artefacto .wasm, calcula o seu digest de conteúdo e envia a entidade. |
--registry | — | Anfitrião do registo de destino (substitui o default_registry do espaço de trabalho) |
--rekor-url | — | URL do registo de transparência Rekor para a assinatura sem chave. Quando omitido, é usada a instância pública do Rekor. |
--sign | false | Assinar o artefacto publicado e anexar a assinatura como um referrer OCI. Quando omitido, a assinatura segue a política do registo de destino. |
--timestamp-url | — | URL opcional da autoridade de carimbo temporal RFC3161 para a assinatura sem chave. |