aggrega push-artifact
単独のデータアーティファクト(ドキュメントバンドルなど)を OCI レジストリに公開します
概要
aggrega push-artifact <file> [flags]説明
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.フラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--dry-run | false | 参照を計算し、提案される |
--media-type | application/vnd.aggrega.docs.v1beta1+tar+gz | OCI アーティファクトのメディアタイプ。デフォルトはドキュメントバンドルのメディアタイプです |
--name | — | 予約済みの docs/ 名前空間内でのアーティファクト名(例: “aggrega-docs” は docs/aggrega-docs に公開されます) |
--registry | — | 公開先のレジストリホスト(ワークスペースの default_registry を上書きします) |
--tag | — | アーティファクトを公開するバージョンタグ(必須) |
ドキュメントバンドルのアーティファクト
ドキュメントバンドルは、カタログエンティティではなく、単独のデータアーティファクト(レンダリングされたドキュメントを gzip 圧縮した tar)です。メディアタイプ application/vnd.aggrega.docs.v1beta1+tar+gz を持ち、これはコンシューマーがレジストリからバンドルをプルする際に目にするアーティファクトタイプです。
バンドルは docs/ リポジトリセグメントの下に公開されます。--name aggrega-docs は
アーティファクトを docs/aggrega-docs に配置し、--tag がバージョンを選択するため、プルの
座標は <registry>/docs/<name>:<tag> になります。例えば
hub.aggrega.ai/docs/aggrega-docs:1.0.0 です。バンドルはカタログエンティティではなく単純なデータ
アーティファクトであるため、その参照とメディアタイプを使用して任意の OCI 互換クライアントで
取得できます。公開されるファイルは --name で指定した名前を持つため、ファイルを名前で書き出すクライアントはその名前で書き出します。
oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 を実行すると、カレントディレクトリに aggrega-docs が
公開時とバイト単位で同一の状態で残ります。
レジストリが書き込みに失敗した場合
公開処理は、ファイル、それを指名する manifest、タグ、そしてその横の公開日という段階に分けて
レジストリに書き込みます。これらの各書き込みは、サーバーエラー、タイムアウト、接続のリセットなど、
後の試行で成功し得る形でレジストリまたはネットワークが失敗させた場合に再試行されます。
それらの失敗は aggrega push に一覧があります。
書き込みは最大 3 回試行され、間隔は 0.5 秒、次に 1 秒です。各試行は失敗したリクエストの再送ではなく
同じバイト列の新たなアップロードであるため、再試行された書き込みは 1 回の試行で得られたはずの結果を反映します。
最後の試行後も失敗する書き込みはコマンドを失敗させ、エラーはその段階を示します。日付の付与の失敗は アーティファクトの反映後に起こります。アーティファクトは公開されたまま残り、コマンドは公開日を 付与できなかったことを伝えて非ゼロで終了します。同じ公開を再度実行すると完了します。アーティファクトは 公開済みと報告され、何もアップロードされず、アーティファクトが日付を持たない場合には、その実行時の 時刻(公開が完了した時刻)を示す日付が付与されます。すでに日付を示しているアーティファクトには何も 付与されず、一覧を読み取れない場合は何も付与せずに非ゼロで終了します。
オフライン
アーティファクトの公開はネットワークの往復を伴うため、オフライン状態(設定ファイルのトップレベルの offline キー、AGGREGA_OFFLINE、または --offline)では、このコマンドはファイルを読み込む前に拒否し、その拒否メッセージは 3 つのうちどれがその状態を設定したかを示します。--dry-run は参照を計算するだけで呼び出しを行わないため、引き続き動作します。オフラインのワークスペースから 1 回の実行だけ公開するには、--offline=false を渡します。
関連項目
- ./aggrega-sign.md — データアーティファクトは事後に参照によって署名されます。 このコマンド自体は署名を付与しません。
- ./aggrega-serve.md — デーモンは同じ公開処理を
aggrega/publishArtifactで提供するため、エディタはセッションを離れずに実行できます。 - ./aggrega-mcp.md — 同じ機能を、アシスタントが呼び出せる
publish-artifactツールとして 提供します。許可する前に、そのページで許可について説明されている内容を確認してください。