aggrega push-artifact
Publicar um artefacto de dados autónomo (como um pacote de documentação) num registo 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
| Flag | Predefinição | Descrição |
|---|---|---|
--dry-run | false | Calcular a referência e imprimir o |
--media-type | application/vnd.aggrega.docs.v1beta1+tar+gz | Tipo de media do artefacto OCI; por predefinição, o tipo de media do pacote de documentação |
--name | — | Nome do artefacto dentro do espaço de nomes reservado docs/ (p. ex., «aggrega-docs» publica em docs/aggrega-docs) |
--registry | — | Anfitrião do registo de destino (substitui o default_registry do espaço de trabalho) |
--tag | — | Tag de versão sob a qual publicar o artefacto (obrigatória) |
O artefacto de pacote de documentação
Um pacote de documentação é um artefacto de dados autónomo — um tar comprimido com gzip de documentação renderizada — e não uma entidade do catálogo. Tem o tipo de media application/vnd.aggrega.docs.v1beta1+tar+gz, que é o tipo de artefacto que um consumidor vê ao obter o pacote do registo.
Os pacotes são publicados sob o segmento de repositório docs/: --name aggrega-docs coloca o artefacto em docs/aggrega-docs, e --tag seleciona a versão, pelo que a coordenada de pull é <registry>/docs/<name>:<tag> — por exemplo, hub.aggrega.ai/docs/aggrega-docs:1.0.0. Como o pacote é um artefacto de dados simples e não uma entidade do catálogo, é obtido com qualquer cliente compatível com OCI usando essa referência e esse tipo de media. O ficheiro publicado tem o nome dado com --name, pelo que um cliente que escreve ficheiros pelo nome o escreve com esse nome: oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 deixa aggrega-docs no diretório atual, byte a byte tal como foi publicado.
Quando o registo falha uma escrita
A publicação escreve no registo por passos — o ficheiro, o manifesto que o nomeia, a tag e depois a data de publicação ao seu lado — e cada uma dessas escritas é repetida quando o registo ou a rede a fazem falhar de uma forma em que uma tentativa posterior pode ter êxito, como um erro de servidor, um tempo limite ou uma ligação reposta; aggrega push lista essas falhas. Uma escrita é tentada no máximo três vezes, com meio segundo e depois um segundo de intervalo, e cada tentativa é um novo envio dos mesmos bytes e não um reenvio do pedido que falhou, pelo que uma escrita repetida deposita o que uma tentativa teria depositado.
Uma escrita que continue a falhar depois da sua última tentativa faz falhar o comando, e o erro nomeia o passo. Uma falha ao anexar a data ocorre depois de o artefacto ter sido depositado: o artefacto continua publicado, e o comando termina com código diferente de zero dizendo que não foi possível anexar a sua data de publicação. Executar novamente a mesma publicação conclui-a: o artefacto é reportado como já publicado, nada é enviado e a data é anexada onde o artefacto não tem nenhuma, indicando o relógio dessa execução — a hora em que a publicação foi concluída. Um artefacto que já indique uma data não recebe nada, e uma listagem que não possa ser lida termina com código diferente de zero sem nada anexado.
Offline
Publicar um artefacto é uma ida e volta pela rede, pelo que, sob a postura offline — a chave de nível superior offline num ficheiro de configuração, AGGREGA_OFFLINE, ou --offline — este comando recusa antes de ler o ficheiro, e a recusa nomeia qual desses três definiu a postura. --dry-run continua a funcionar, porque calcula a referência e não faz nenhuma chamada. Para publicar numa execução a partir de um espaço de trabalho offline, passe --offline=false.
Ver também
- ./aggrega-sign.md — um artefacto de dados é assinado posteriormente, por referência; este comando não anexa nenhuma assinatura própria.
- ./aggrega-serve.md — o daemon disponibiliza a mesma publicação em
aggrega/publishArtifact, para que um editor a possa executar sem sair da sessão. - ./aggrega-mcp.md — a mesma capacidade, na forma da ferramenta
publish-artifact, que um assistente pode chamar. Leia o que essa página diz sobre a permitir antes de o fazer.