콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

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-runfalse참조를 계산하고 제안된 :를 출력하며, 네트워크 호출은 건너뜁니다
--media-typeapplication/vnd.aggrega.docs.v1beta1+tar+gzOCI 아티팩트 미디어 유형입니다. 기본값은 문서 번들 미디어 유형입니다
--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를 게시된 그대로 바이트 단위까지 동일하게 남깁니다.

레지스트리가 쓰기에 실패하는 경우

게시는 레지스트리에 여러 단계로 씁니다. 파일, 그 파일을 지정하는 매니페스트, 태그, 그리고 그 옆의 게시 날짜 순입니다. 이러한 각 쓰기는 서버 오류, 시간 초과, 연결 재설정처럼 이후 시도에서 성공할 수 있는 방식으로 레지스트리나 네트워크가 실패시킨 경우 재시도됩니다. 이러한 실패 목록은 aggrega push에 있습니다. 쓰기는 최대 세 번 시도되며, 시도 간격은 처음에 0.5초, 다음에 1초입니다. 각 시도는 실패한 요청을 다시 보내는 것이 아니라 같은 바이트를 새로 업로드하는 것이므로, 재시도된 쓰기는 한 번의 시도가 남겼을 결과를 그대로 남깁니다.

마지막 시도 후에도 쓰기가 실패하면 명령이 실패하며, 오류에는 해당 단계가 명시됩니다. 날짜 첨부 실패는 아티팩트가 이미 게시된 뒤에 발생합니다. 아티팩트는 게시된 상태로 남고, 명령은 게시 날짜를 첨부할 수 없었다는 메시지와 함께 0이 아닌 코드로 종료됩니다. 같은 게시를 다시 실행하면 게시가 완료됩니다. 아티팩트는 이미 게시된 것으로 보고되고, 아무것도 업로드되지 않으며, 아티팩트에 날짜가 없는 경우 그 실행 시점의 시각, 즉 게시가 완료된 시각을 나타내는 날짜가 첨부됩니다. 이미 날짜가 있는 아티팩트에는 아무것도 첨부되지 않으며, 목록을 읽을 수 없으면 아무것도 첨부하지 않고 0이 아닌 코드로 종료됩니다.

오프라인

아티팩트 게시는 네트워크 왕복이 필요하므로, 오프라인 모드(구성 파일의 최상위 offline 키, AGGREGA_OFFLINE 또는 --offline)에서는 이 명령이 파일을 읽기 전에 실행을 거부하며, 거부 메시지에는 이 세 가지 중 어느 것이 모드를 설정했는지가 명시됩니다. --dry-run은 참조를 계산할 뿐 호출을 하지 않으므로 계속 동작합니다. 오프라인 워크스페이스에서 한 번의 실행에 한해 게시하려면 --offline=false를 전달합니다.

참고 항목

  • ./aggrega-sign.md — 데이터 아티팩트는 게시 후에 참조를 통해 서명됩니다. 이 명령은 자체적으로 서명을 첨부하지 않습니다.
  • ./aggrega-serve.md — 데몬은 같은 게시 기능을 aggrega/publishArtifact로 제공하므로, 편집기에서 세션을 벗어나지 않고 실행할 수 있습니다.
  • ./aggrega-mcp.md — 어시스턴트가 호출할 수 있는 publish-artifact 도구로 같은 기능을 제공합니다. 허용하기 전에 해당 페이지에서 허용에 관한 설명을 읽으십시오.