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-artifact

Publicar um artefato de dados independente (como um pacote de documentação) em um registry OCI

Sinopse

aggrega push-artifact <file> [flags]

Descrição

Publish a standalone data artifact — a documentation bundle or any other non-entity blob — to an OCI registry under the reserved docs/ namespace. Unlike push, which bundles a catalog entity and dispatches on its kind, push-artifact carries opaque bytes: it reads the file, packs it under the given media type (defaulting to the documentation-bundle media type), and tags it at docs/<name>:<tag>. The published artifact is signed separately by reference with aggrega sign. Beside it, push-artifact states when it published, as a small published-at attachment carrying this machine's clock in UTC to the second; the attachment moves no digest and changes no tag.

Flags

FlagPadrãoDescrição
--dry-runfalseCalcula a referência e exibe o : proposto; pula a chamada de rede
--media-typeapplication/vnd.aggrega.docs.v1beta1+tar+gzMedia type do artefato OCI; o padrão é o media type do pacote de documentação
--name—Nome do artefato dentro do namespace reservado docs/ (por exemplo, “aggrega-docs” é publicado em docs/aggrega-docs)
--registry—Host do registry de destino (substitui o default_registry do workspace)
--tag—Tag de versão com a qual publicar o artefato (obrigatória)

O artefato do pacote de documentação

Um pacote de documentação é um artefato de dados independente — um tar compactado com gzip de documentação renderizada — em vez de uma entidade de catálogo. Ele tem o media type application/vnd.aggrega.docs.v1beta1+tar+gz, que é o tipo de artefato que um consumidor vê ao fazer o pull do pacote a partir do registry.

Os pacotes são publicados sob o segmento de repositório docs/: --name aggrega-docs coloca o artefato em docs/aggrega-docs, e --tag seleciona a versão, de modo que a coordenada de pull é <registry>/docs/<name>:<tag> — por exemplo, hub.aggrega.ai/docs/aggrega-docs:1.0.0. Como o pacote é um simples artefato de dados e não uma entidade de catálogo, ele é obtido com qualquer cliente compatível com OCI usando essa referência e esse media type. O arquivo publicado leva o nome dado com --name, de modo que um cliente que grava arquivos por nome o grava com esse nome: oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 deixa aggrega-docs no diretório atual, byte a byte como foi publicado.

Quando o registry faz uma gravação falhar

A publicação grava no registry em etapas — o arquivo, o manifesto que o nomeia, a tag e, em seguida, a data de publicação ao lado — e cada uma dessas gravações é repetida quando o registry ou a rede a fazem falhar de um modo em que uma tentativa posterior pode ter sucesso, como um erro do servidor, um tempo limite ou uma conexão redefinida; aggrega push lista essas falhas. Uma gravação é tentada no máximo três vezes, com meio segundo e depois um segundo de intervalo, e cada tentativa é um novo upload dos mesmos bytes, e não um reenvio da solicitação que falhou, de modo que uma gravação repetida deposita o que uma única tentativa teria depositado.

Uma gravação que ainda falha após sua última tentativa faz o comando falhar, e o erro indica a etapa. Uma falha ao anexar a data ocorre depois que o artefato foi depositado: o artefato continua publicado, e o comando sai com código diferente de zero informando que não foi possível anexar sua data de publicação. Executar a mesma publicação novamente a conclui: o artefato é relatado como já publicado, nada é enviado, e a data é anexada onde o artefato não tem nenhuma, informando o relógio dessa execução — o momento em que a publicação foi concluída. Um artefato que já informa uma data não recebe nada, e uma listagem que não pode ser lida sai com código diferente de zero sem anexar nada.

Offline

Publicar um artefato é uma ida e volta pela rede, então no modo offline — a chave de nível superior offline em um arquivo de configuração, AGGREGA_OFFLINE ou --offline — este comando recusa antes de ler o arquivo, e a recusa indica qual desses três definiu o modo. --dry-run continua funcionando, porque calcula a referência e não faz nenhuma chamada. Para publicar em uma única execução a partir de um workspace offline, passe --offline=false.

Veja também

  • ./aggrega-sign.md — um artefato de dados é assinado posteriormente, por referência; este comando não anexa nenhuma assinatura própria.
  • ./aggrega-serve.md — o daemon oferece a mesma publicação em aggrega/publishArtifact, de modo que um editor pode executá-la sem sair da sessão.
  • ./aggrega-mcp.md — a mesma capacidade como a ferramenta publish-artifact, que um assistente pode chamar. Leia o que essa página diz sobre permiti-la antes de fazê-lo.