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

aggrega push

aggrega push는 카탈로그 엔터티를 OCI 레지스트리에 게시하며, 다른 워크스페이스는 aggrega pull로 이를 해석할 수 있습니다.

동작

aggrega push는 단일 엔터티 YAML을 읽고, 전송을 위해 번들로 묶은 다음, 리포지토리 경로를 소문자로 바꾸어 <registry>/<kind>/<metadata.name>:<metadata.version>에 푸시합니다. Recipe 또는 FeatureRecipe는 spec.capability를, Plugin은 metadata.pluginType을 kind와 name 사이의 세그먼트로 포함합니다. 설치된 바이너리가 게시하는 엔터티 kind를 확인하려면 aggrega push --list-kinds를 실행합니다. 한 줄에 하나의 kind가 정렬되어 출력되고 그 외에는 아무것도 출력되지 않으므로 스크립트가 직접 읽을 수 있습니다. 이 집합에는 카탈로그 작성 kind와 함께, 재사용 가능한 모듈인 Aggregate, 그리고 컴파일러가 라우팅하고 런타임이 실행하는 WebAssembly 아티팩트에 대한 콘텐츠 주소 참조인 Plugin이 포함됩니다. Plugin은 카탈로그 작성 kind가 아니라 구조적으로 게시 가능한 아티팩트입니다. 게시 가능 여부는 엔터티가 어떻게 사용되는지가 아니라 엔터티 자체의 속성입니다. Aggregate는 나중에 Release의 최상위 spec.aggregate로 참조되든 다른 Aggregate의 aggregates: 블록에 중첩되든 게시할 수 있습니다. Release와 Manifest는 카탈로그 아티팩트가 아니라 배포 측 입력이므로 거부됩니다.

번들링

push는 엔터티 문서와 엔터티 자신이 이름을 지정한 그 옆의 파일만 게시하며, 디렉터리의 다른 것은 게시하지 않습니다. 엔터티가 지정하는 파일은 다음과 같습니다.

  • Recipe 또는 FeatureRecipe의 경우, 로컬 source:(디렉터리는 엔터티와 함께 배포되는 파일에서 설명하는 대로 entity.lock에 기록된 무시 규칙이 유지하는 그 아래의 모든 파일과 함께 전송됩니다), valuesMapping:, workload:, artifacts: 항목이 $import:로 가져오는 각 파일, 그리고 그 옆의 entity.lock;
  • Component 또는 Feature의 경우, spec.schema, 필러 또는 usesSchema 소켓이 $import:로 가져오는 각 스키마 파일(가져온 파일이 다시 가져오는 모든 파일 포함).

Aggregate, Plugin 및 라이브러리 종류는 문서 옆의 파일을 지정하지 않습니다. 디렉터리에 있는 메모, README, 다른 엔터티의 파일 또는 빌드 출력은 이름이 무엇이든 게시되지 않습니다. 엔터티가 지정하는 파일 중 심볼릭 링크는 따라가지 않고 거부되며(A symbolic link sits among the files an entity carries (엔터티가 포함하는 파일 중에 심볼릭 링크가 있음)), 엔터티 디렉터리 밖으로 이어지는 링크인 디렉터리를 거쳐 엔터티가 지정하는 경로도 패킹 전에 거부됩니다(A path names content outside the entity’s own directory (경로가 엔터티 자신의 디렉터리 밖의 콘텐츠를 지정함)).

형태는 여기서 결정됩니다. 아무것도 지정하지 않는 엔터티는 해당 종류의 +yaml 미디어 타입으로 문서 그대로 게시됩니다. 파일을 지정하는 엔터티는 문서와 해당 파일을 디렉터리 내 위치 그대로 담은 .tar.gz로, 해당 종류의 +tar+gz 미디어 타입으로 게시됩니다. 따라서 콘텐츠가 모두 인라인인 Recipe는 문서로 게시되고, 스키마를 파일에서 가져오는 Component는 아카이브로 게시됩니다. Catalog and Registry §6에 모든 종류의 두 미디어 타입이 나열되어 있습니다.

아카이브의 각 파일은 디스크상의 권한 비트와 관계없이 모드 0644를 가지며 타임스탬프가 없습니다. 체크아웃은 자체 권한 비트로 파일을 쓰며, 실행 비트를 기록하지 않는 시스템은 다른 시스템이 실행 파일로 체크아웃하는 것을 일반 파일로 체크아웃하므로, 아카이브는 디스크에서 읽은 모드를 담지 않습니다. 따라서 한 커밋의 두 체크아웃은 umask나 생성된 시스템과 관계없이 같은 파일을 게시하며, 스크립트의 실행 비트를 바꾸어도 게시되는 내용은 달라지지 않습니다.

push는 아카이브에 포함된 항목 중 Windows가 그대로 보관할 수 없는 각 항목에 대해 경고합니다. 이는 CON, AUX, NUL처럼 장치 이름을 딴 부분이 있는 경로(대소문자와 뒤따르는 확장자에 관계없이, 예: aux/x.yaml)이거나, report.처럼 마침표나 공백으로 끝나는 부분이 있는 경로입니다. Windows에서 aggrega는 이러한 항목의 압축 해제를 거부하므로 Windows 작업 공간에서는 해당 버전을 사용할 수 없습니다. 경고는 모든 플랫폼에서 표준 오류에 항목당 한 줄씩, 게시 자체의 보고보다 먼저 출력됩니다. 엔터티 문서 자신의 파일 이름은 그것이 지정하는 파일과 함께 판단되며, 아무것도 지정하지 않는 엔터티는 문서만으로 게시되므로 경고를 받지 않습니다. 경고는 아무것도 거부하지 않습니다. push는 경고가 없을 때와 똑같이 진행되거나 거부되며, --dry-run도 같은 방식으로 경고합니다. A published archive carries an entry Windows cannot use (게시된 아카이브에 Windows가 사용할 수 없는 항목이 있음)에서 해당 줄과 대처 방법을 보여 줍니다.

템플릿으로 작성된 로컬 source:는 디렉터리 전체를 담습니다. ./charts/{{ .values.flavour }}와 같은 템플릿은 Release가 값을 채워야 비로소 디렉터리를 지정하므로, 게시 시점에는 어느 디렉터리가 될지 알 수 없습니다. 이러한 엔터티는 기록된 무시 규칙이 유지하는 자신의 디렉터리 내 모든 파일을 담으며(.aggregaignore는 제외되며, 그 규칙은 lock 안에 담겨 전송됩니다), push는 다른 정보 아래에 이를 알립니다.

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 it

지정되지 않은 것은 전송되지 않으며, 이를 발견하는 쪽은 소비자입니다. 엔터티가 위 필드 중 하나로 지정하지 않고 의존하는 파일은 게시물에 포함되지 않으며, push가 아니라 소비자의 빌드가 캐시 슬롯 안에서 누락된 경로를 지목하며 실패합니다. 엔터티에 필요한 모든 파일을 해당 필드 중 하나로 지정하십시오.

게시된 각 파일은 아티팩트의 manifest에 이름이 기재되므로, oras와 같은 범용 OCI 클라이언트는 해당 이름의 파일로 씁니다. 문서로 게시된 엔터티는 entity.yaml, 파일과 함께 게시된 엔터티는 entity.tar.gz, Plugin은 엔터티에 entity.yaml, 실행 파일에 entity.wasm입니다. 이름은 게시에 사용한 파일이 아니라 미디어 타입에서 정해지므로, 이름을 바꾼 파일에서 같은 콘텐츠를 게시해도 같은 아티팩트가 게시됩니다. Catalog and Registry §6에 게시되는 모든 형태와 각각이 저장되는 파일이 나열되어 있습니다.

Recipe의 원격 source: URL(OCI 차트 참조, HTTPS 차트 또는 프래그먼트 URL, Git 모듈)은 게시된 YAML에 그대로 보존되며, 가져와서 아티팩트에 포함하지 않습니다. 소비자는 자신의 pull 시점에 원격 소스를 독립적으로 해석하고 고정합니다. 이를 통해 카탈로그 엔터티 배포와 소스 아티팩트 해석을 별개의 관심사로 유지합니다.

Aggregate는 자신만의 단일 문서로 게시되며, aggregates:에서 참조하는 하위 aggregate는 아티팩트에 번들링되지 않습니다. 각 하위 aggregate는 별도로 게시된 Aggregate이며, 소비자가 pull 시점에 식별자로 독립적으로 해석하고 고정합니다. 이는 원격 소스에 적용되는 것과 같은 배포 분리 원칙입니다.

디렉터리당 하나의 엔터티

아카이브는 엔터티 파일을 그 엔터티가 지정하는 파일들과 함께 담으므로, 꺼낼 때 엔터티를 다시 찾아야 합니다. 소비자는 엔터티가 지닌 프리앰블로 이를 찾습니다. 번들 최상위에 있는 문서 중 kind:가 게시 가능한 엔터티 종류인 문서가 엔터티입니다. 엔터티를 작성한 파일의 이름은 무엇이든 될 수 있으며 — recipe.yaml은 요구 사항이 아니라 카탈로그의 관례입니다 — 엔터티 옆에 있는 compose 조각, 차트 템플릿 또는 Kubernetes 매니페스트는 엔터티로 오인되지 않습니다. 이들은 다른 종류를 선언하거나 종류를 전혀 선언하지 않기 때문입니다. 더 아래, source/ 트리 안에 있는 엔터티 문서는 엔터티 자체가 아니라 엔터티가 함께 배포하는 콘텐츠이며 고려 대상이 되지 않습니다.

push는 다른 엔터티와 디렉터리를 공유하는 엔터티를 거부합니다. 모든 종류는 자기만의 디렉터리를 가지며, 예외는 워크스페이스 루트에 나란히 두는 Aggregate, Release, Manifest입니다. 그 밖의 종류에 대해 push는 엔터티로 다른 작업을 하기 전에 — pin 단계, 서명 정책, 번들보다 먼저 — 같은 디렉터리에 다른 엔터티 문서가 없는지 확인하고, 있으면 방해가 되는 각 엔터티를 지목하며 거부합니다. 이는 push에 pin을 요청했는지와 관계없이 이루어집니다. aggrega pin도 같은 디렉터리를 같은 문구로 거부하며, 해당 중단은 An entity shares its directory with another entity (엔터티가 다른 엔터티와 디렉터리를 공유합니다)입니다. 엔터티 옆에 있는 엔터티 종류가 아닌 문서 — 차트 파일, compose 조각, README — 는 방해가 되지 않으며, 하위 디렉터리에 있는 것도 마찬가지입니다. 엔터티 옆의 각 문서는 워크스페이스 안에서만 읽히고, 워크스페이스 밖에서 지정한 엔터티라면 엔터티 자신의 디렉터리 안에서만 읽힙니다. 따라서 밖으로 이어지는 링크인 문서는 읽히지 않은 채 그 링크를 지목하며 push를 중단시킵니다. 이는 워크스페이스 경계에서 설명합니다.

이 규칙은 하나의 entity.lock이 하나의 엔터티에 속하도록 유지합니다. lock의 파일 이름은 모든 엔터티에 대해 같으므로, 한 디렉터리에 작성된 두 엔터티는 그 디렉터리에 들어갈 수 있는 하나의 lock을 공유하게 됩니다. 이 규칙은 디렉터리에서 무언가를 생성할 때만 판정되므로, 여러 엔터티를 담은 디렉터리도 여전히 로드, lint, 빌드됩니다.

디렉터리의 이름은 판정되지 않습니다. 디렉터리에 혼자 있는 엔터티는 그 디렉터리가 어디에 있든 자신의 metadata.version으로 게시됩니다. 표준 라이브러리 카탈로그가 따르는 레이아웃인 <name>/<version>/은 관례입니다. 다른 클라이언트가 두 엔터티를 담은 디렉터리에서 게시한 아티팩트도 안전하게 읽힙니다. 이를 pull하면 어느 한쪽으로 응답하지 않고 두 문서를 모두 지목하며 중단되며, 이는 errors/fatal-halts.md에 정리되어 있습니다.

번들링 전에 엔티티 읽기

push는 Component, Feature, Recipe 또는 FeatureRecipe를 빌드가 읽는 방식과 똑같이 읽으며, 그 읽기가 거부하는 엔티티를 거부합니다 — 같은 이유와 같은 짧은 코드로, 번들이 빌드되기 전이자 대상 레지스트리에 접속하기 전에 거부합니다. 따라서 해당 종류의 스키마를 통과하지 못하는 문서, 엔티티 자체 디렉터리 밖의 콘텐츠를 가리키는 경로, Component나 Feature가 $import:로 가져오는 스키마 중 없거나 사용할 수 없는 스키마는 게시되지 않고 게시 시점에 거부됩니다. 이들은 모두 소비자의 첫 빌드가 거부할 엔티티입니다. 디렉터리를 벗어나는 경로는 엔티티와 함께 전달되지 않을 파일을 가리키기도 합니다. 게시물이 담는 모든 파일은 엔티티 자체 디렉터리에서 가져오기 때문입니다. A path names content outside the entity’s own directory (경로가 엔티티 자체 디렉터리 밖의 콘텐츠를 가리킴)를 참조하십시오.

Recipe 또는 FeatureRecipe는 다음 섹션에서 설명하는 대로 핀을 비교할 때 이 방식으로 읽히므로, push에 핀 고정이 요청되었는지와 엔티티에 고정할 것이 있는지와 관계없이 읽기가 수행됩니다. 네 가지 종류는 모두 번들이 빌드되기 직전에도 이 방식으로 읽힙니다. 그 읽기가 엔티티가 가리키는 파일을 알려 주기 때문입니다. Aggregate와 라이브러리는 파일을 가리키지 않으므로 이 방식으로 읽히지 않습니다. Plugin도 파일을 가리키지 않으며, Plugin 게시에서 설명하듯이 .wasm보다 먼저 해당 종류의 스키마에 대해 읽힙니다.

Plugin 게시

Plugin은 --plugin으로 지정한 .wasm과 함께 게시되며, push는 어떤 바이트도 게시되기 전, 그리고 레지스트리에 접속하기 전에 이 둘을 판정합니다. --dry-run은 게시할 때와 똑같이 이 둘을 판정합니다.

엔터티는 먼저 해당 종류의 스키마에 따라 읽힙니다. 카탈로그 로드가 읽는 방식과 같으며, .wasm을 읽기 전에 이루어집니다. 따라서 시맨틱 버전이 아닌 metadata.version(예: 415148e 같은 단순 커밋)은 스키마 자체의 조건에 따라 필드 이름과 함께 거부되며, spec.abiVersion 누락처럼 스키마에서 벗어난 다른 모든 경우도 마찬가지입니다. 여기서 무엇이 시맨틱 버전으로 인정되는지는 metadata.version에 대한 스키마 자체의 패턴이 정하며, push는 자체 규칙을 추가하지 않습니다.

그런 다음 .wasm을 로드하여 엔터티와 대조합니다. 플러그인이 제공한다고 보고하는 내용은 엔터티가 주장하는 내용과 일치해야 하고, 엔터티가 기록한 명령 집합과 호스트 함수는 플러그인과 맞아야 하며, 플러그인이 자신의 빌드에 대해 보고하는 버전은 metadata.version과 같아야 합니다. A Plugin entity’s recorded version does not match the plugin (Plugin 엔터티에 기록된 버전이 플러그인과 일치하지 않음)을 참조하십시오.

커밋되지 않은 변경 사항이 있는 작업 트리에서 빌드한 .wasm은 거부됩니다. 이러한 빌드는 보고하는 버전 끝에 -dirty 표시를 붙입니다(1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty). 이는 유효한 시맨틱 버전이지만, 빌드된 내용을 담고 있지 않은 커밋을 가리키므로, 게시된 버전으로부터 게시된 내용을 누구도 다시 빌드할 수 없습니다. push는 이를 거부하며 버전과 해결 방법을 알려 줍니다. 재빌드가 보고하는 버전을 엔터티에 복사하는 대신, 릴리스 태그가 가리키는 커밋을 깨끗하게 체크아웃하여 플러그인을 빌드해 릴리스 버전 자체를 보고하게 하십시오. 변경 사항을 릴리스하려면 먼저 엔터티의 metadata.version을 새 릴리스로 설정하여 커밋하고 그 커밋에 태그를 지정하십시오. 1.0.0-3-g1a2b3c4처럼 커밋에서 빌드한 개발 버전과 1.0.0-rc.1 같은 프리릴리스는 모두 게시됩니다. 이 거부는 A plugin was built from a working tree with uncommitted changes (커밋되지 않은 변경 사항이 있는 작업 트리에서 플러그인이 빌드됨)입니다.

게시 전 고정

Recipe 또는 FeatureRecipe는 자신이 읽는 입력(전체 주소로 작성된 원격 source:, artifacts 항목이 가져오는 파일, 옆에 있는 source:의 파일)에 대한 고정 정보를 옆에 있는 entity.lock에 담으며, push는 그 파일을 엔터티와 함께 게시합니다. 고정은 게시 전에 실행하는 단계인 aggrega pin이며, 이 단계가 기록한 lock을 커밋합니다.

push는 lock에 해당 고정 정보가 기록되지 않은 엔터티를 거부합니다. push는 번들을 빌드하기 전에 고정 단계가 엔터티에 대해 기록할 내용을 계산하고, 이를 옆에 있는 entity.lock과 비교합니다. 고정 정보가 없거나, lock에 있는 고정 정보와 입력이 더 이상 일치하지 않으면, push는 아카이브를 빌드하거나 레지스트리에 접속하기 전에 중단합니다. 거부 메시지는 엔터티와 그러한 모든 입력(각각 remote source, imported file 또는 local source file), 그리고 실행할 방법을 알려 줍니다. 엔터티에 aggrega pin을 실행하거나, 방금 실행한 push에 --pin-sources를 지정하거나, 워크스페이스의 모든 push에 pin_sources_at_push를 사용합니다. 이는 pull이 같은 lock에 대해 발생시키는 것과 같은 거부인 An entity reads an input the lock beside it records no pin for (엔터티가 옆의 lock에 고정 정보가 기록되지 않은 입력을 읽음)이며, push 고유의 해결 방법이 함께 제시됩니다. 따라서 push가 게시하는 Recipe 또는 FeatureRecipe는 게시 시점에 고정 단계가 기록했을 모든 고정 정보를 기록한 lock을 번들 안에 담습니다.

고정할 것이 없어 그대로 게시되는 엔터티는 두 종류입니다. 원격 소스를 읽지 않고, 파일을 가져오지 않으며, 로컬 소스를 지정하지 않는 엔터티와, 원격 소스 좌표가 템플릿으로 채워지는 Recipe입니다. 이러한 소스는 Release가 템플릿을 채운 후에야 아티팩트를 지정하므로, 그 고정 정보는 각 Release의 lockfile에 속하며, push는 엔터티 옆에 고정 정보를 요구하지 않습니다. Component, Feature, 라이브러리, Aggregate 또는 Plugin은 lock이 기록하는 것을 읽지 않으므로 여기서 거부되지 않습니다.

원격 소스의 고정 정보를 비교하려면 aggrega pin과 마찬가지로 소스를 가져와야 합니다. 더 이상 일치하지 않는 고정 정보는 소스가 현재 제공하는 내용과 대조해야만 드러나기 때문입니다. 따라서 이러한 소스가 있는 엔터티에 대한 push는 레지스트리보다 먼저 소스의 호스트에 접속합니다. 비교는 고정 단계와 마찬가지로 카탈로그를 통해 Recipe 또는 FeatureRecipe를 읽으므로, 카탈로그가 읽기를 거부하는 것(예: 해당 종류의 스키마를 통과하지 못하는 문서)은 카탈로그 자체의 사유와 함께 여기서 거부됩니다.

워크스페이스를 찾지 못했고 지정되지도 않은 경우, 비교를 위해 원격 소스를 가져와야 하는 push는 aggrega pin과 마찬가지로 가져오기 전에 거부됩니다. 비교는 고정 단계와 똑같이, 엔터티가 전체 주소로 작성한 각 원격 소스를 아티팩트 캐시로 가져오며, 워크스페이스를 찾지 못한 폴더에 캐시를 쓰면 그 폴더가 워크스페이스가 됩니다. 따라서 루트를 지정하는 것도, 루트를 고정하는 것도 없으면(push를 실행하는 폴더에서, 또는 절대 경로로 지정된 엔터티의 경우 엔터티 자체의 폴더에서), 그러한 소스가 있는 Recipe 또는 FeatureRecipe의 push는 dry run과 --pin-sources를 포함하여 소스를 가져오기 전에 중단되며, 소스와 폴더, 그리고 두 가지 해결 방법을 알려 줍니다. --workspace-root 또는 AGGREGA_WORKSPACE_ROOT로 워크스페이스를 지정하거나, 해당 폴더에 workspace: 블록을 담은 .aggrega-config.yaml을 두는 것입니다. 비교는 위의 두 종류의 엔터티와 소스가 로컬인 엔터티에 대해서는 아무것도 가져오지 않으므로, 이들은 각각 lock과 비교된 후 다른 곳과 마찬가지로 그곳에서 게시됩니다. 그 밖의 모든 종류는 lock의 적용을 받지 않으며 이 이유로 거부되지 않습니다. 이 사항이 적용되는 다른 명령은 Configuration에 나열되어 있습니다.

aggrega push --pin-sources는 같은 단계를 먼저 대신 실행합니다. 이 단계는 번들이 빌드되기 전에 실행되므로, 기록된 lock이 게시된 아티팩트에 포함되고 게시된 다이제스트가 이를 포괄합니다. 또한 엔터티를 판정하는 다른 모든 거부보다 먼저 실행되므로, 판정 대상은 고정된 상태의 엔터티입니다. 위의 디렉터리 규칙만이 그보다 먼저 적용되는데, 이 단계가 디렉터리에 있는 하나의 lock을 기록하기 때문입니다. 이 단계는 aggrega pin과 같은 바이트를 기록하므로, 해당 실행에서 위의 거부는 발생하지 않습니다. 방금 기록된 lock이 거부가 비교할 내용을 정확히 기록하기 때문입니다. 워크스페이스 키 pin_sources_at_push는 이를 모든 push의 기본값으로 만들고, --pin-sources=false는 한 번의 실행에서 이 단계를 건너뛰며, 그러면 거부가 다시 적용됩니다. 이 단계는 엔터티 옆에 기록하므로 쓰기 가능한 위치가 필요하며, push는 지정한 문서를 게시하므로 항상 그러한 위치를 갖습니다.

--dry-run은 게시가 응답할 방식대로 응답합니다. --pin-sources 없이는 게시와 똑같이 고정되지 않은 엔터티를 거부하므로, 번들을 보고하는 dry run은 이 거부를 통과하는 것입니다. --pin-sources를 지정하면 고정 단계가 dry run으로 실행됩니다. 기록할 lock을 출력하고 아무것도 쓰지 않으며, 이어지는 번들 정보는 해당 lock이 없는 현재 상태의 디렉터리를 설명합니다. 따라서 다이제스트는 lock이 없는 게시의 다이제스트이며, lock이 새로 생기는 경우에는 크기와, 다른 것을 지정하지 않는 엔터티의 경우 미디어 유형도 마찬가지입니다. 게시라면 먼저 고정했을 것이므로 거부는 발생하지 않습니다.

모범 사례: 이미 게시한 버전에 대한 변경은 새 버전에 넣은 다음 고정합니다. 엔터티를 새 버전 디렉터리로 복사하고, 그곳에서 변경한 후 고정하고, 그것을 게시합니다. 이 중 제품이 강제하는 절반은 다음 섹션의 내용으로, 이미 게시된 버전에 다른 내용을 게시하는 것은 거부됩니다. 나머지 절반, 즉 이미 게시된 버전을 자신의 워크스페이스에서 편집한 후 다시 고정하지 않는 것은 직접 지켜야 합니다. 게시하지 않은 엔터티를 다시 고정하는 것은 정당하므로 로컬에서는 아무것도 이를 거부하지 않습니다.

레지스트리, 태그, 콘텐츠 주소 지정

대상 레지스트리는 --registry <ref>가 주어지면 그 값이고, 그렇지 않으면 워크스페이스의 default_registry(기본값 hub.aggrega.ai)입니다. 태그는 엔터티의 metadata.version이고, 리포지토리 경로는 엔터티의 종류와 이름에서 도출되므로, 게시된 버전이 놓이는 위치는 게시한 디렉터리에 따라 달라지지 않습니다.

default_registry는 리포지토리 경로를 포함할 수 있으며, 이를 통한 게시는 그 경로 아래에 놓입니다. default_registry: ghcr.io/acme인 경우, 버전 1.0.0의 Component core/api-server는 ghcr.io/acme/component/core/api-server:1.0.0에 게시됩니다. 이는 같은 기본값을 통한 pull이 가져오는 위치이므로, 여기서 첨부한 서명이 그 pull이 찾는 서명입니다. --registry는 호스트를 지정하며, 이것이 지정한 게시는 경로 없이 그 호스트에 놓입니다. 대상을 어떤 방식으로 지정하든, 적용되는 서명 요구 사항과 서명 구성은 그 호스트에 대해 유지되는 것입니다. 경로가 다른 정책을 선택하는 일은 없습니다. 경로의 표기법은 레지스트리 호스트를 쓰는 방법에 설명되어 있습니다.

매니페스트는 게시된 바이트의 다이제스트를 명시하고, 잠금 파일은 그 바이트가 담은 내용의 다이제스트를 기록합니다. push가 작성하는 OCI 매니페스트는 게시된 문서나 아카이브의 다이제스트를 명시하며, aggrega pull은 이와 일치하지 않는 다운로드를 거부하므로, 게시와 pull 사이에 변경된 바이트가 탐지됩니다. pull이 작성하는 잠금 파일은 엔터티를 다른 다이제스트로 기록합니다. 바로 콘텐츠의 다이제스트로, 각 파일의 경로와 바이트로 이루어지며 아카이브가 어떻게 압축되었는지나 파일에 어떤 권한 비트가 있었는지는 포함하지 않습니다. 이는 작성자 자신의 워크스페이스에서 pull이 카탈로그 디렉터리의 같은 엔터티에 대해 기록하는 다이제스트이므로, 작성자와 한 게시물의 모든 소비자가 같은 값을 기록하며, 어느 쪽의 빌드든 더 이상 이와 일치하지 않는 콘텐츠를 거부합니다. 두 다이제스트는 서로 다른 질문에 답합니다. 매니페스트의 다이제스트는 다운로드를 검사하고, 잠금 파일의 다이제스트는 엔터티의 식별자입니다.

기존 버전 위에 게시하기

바이트를 업로드하기 전에 aggrega push는 쓰려는 참조에 대상 레지스트리가 이미 보유한 것을 확인하고, 이를 현재 콘텐츠와 비교합니다. 결과는 세 가지입니다.

  • 아직 아무것도 게시되지 않은 경우 — push가 진행되어 정상적으로 게시합니다.
  • 같은 콘텐츠인 경우 — 아무것도 업로드하지 않으며, 명령은 해당 버전이 이미 게시되었다고 보고하므로 반복하거나 재시도한 push는 오류가 아닙니다. 이전 push가 첨부하지 못한 것(서명 또는 게시 날짜)은 이전 push가 일부만 남긴 게시 완료하기에서 설명하는 대로 이때 첨부됩니다.
  • 다른 콘텐츠인 경우 — push가 중단되며, 이미 게시된 다이제스트와 쓰려던 다이제스트를 표시합니다. 이를 강제로 통과시키는 플래그는 없습니다.

따라서 이미 게시된 버전은 그 버전으로 게시된 바이트를 계속 가리킵니다. 변경된 콘텐츠는 새 metadata.version으로 게시합니다. 다음 질문, 즉 버전을 얼마나 올려야 하는지는 aggrega lint --pre-publish가 이전에 게시된 버전과 비교해 변경을 분류하여 답합니다.

--dry-run은 push가 쓸 다이제스트를 출력합니다. 이를 쓸 참조도 함께 출력합니다.

aggrega push (dry-run): <reference>:<tag> (<digest>)

이는 push 자체가 이미 게시된 것과 비교하는 다이제스트로, 콘텐츠만으로 같은 방식으로 계산되며, 출력할 때 어떤 레지스트리에도 접속하지 않습니다. 따라서 아무것도 push하기 전에 현재 콘텐츠를 어떤 버전이 게시된 다이제스트와 대조할 수 있습니다. 게시된 버전에서 둘이 다르면 push는 거부됩니다. --pin-sources를 사용하면 게시 전 고정하기에서 설명하는 대로 현재 상태의 디렉터리 다이제스트가 됩니다.

이전 push가 일부만 남긴 게시 완료하기

push는 콘텐츠를 먼저 쓰고 서명과 게시 날짜를 나중에 첨부하므로, 재시도 후에도 이 첨부 중 하나에 실패한 push는 그것 없이 콘텐츠만 게시된 상태로 남기고, 첨부하지 못한 것을 표시하며 0이 아닌 코드로 종료합니다. 같은 push를 다시 실행하면 해당 게시가 완료됩니다. 콘텐츠가 이미 게시된 것을 확인하고 Already published: 줄을 출력하며, 아무것도 업로드하지 않고 버전에 아직 없는 것을 첨부합니다. 각각에 대해 첫 게시에서 출력하는 줄을 출력합니다.

  • 서명(이 push가 서명하는 경우). 버전에 이 게시의 것으로 인정되는 서명이 없을 때 첨부됩니다. 구성이 대상 호스트에 대해 신뢰 정책(public_key 또는 trusted_identities, 또는 hub.aggrega.ai의 경우 내장 기준)을 고정하면, 서명은 그 정책으로 검증될 때 인정되므로 정책이 허용하지 않는 서명은 결코 게시 자체의 서명으로 간주되지 않습니다. 정책이 둘 다 고정하지 않으면 어떤 서명도 이를 기준으로 검증될 수 없으므로, 버전에 있는 모든 서명이 인정되고 push는 서명이 없는 버전에만 서명합니다. 이 경우 검증으로 판단하면 실행할 때마다 서명을 하나씩 더 첨부하게 됩니다.
  • 게시 날짜: 날짜 규칙에 따라 날짜가 필요하고(방금 첨부한 서명 또는 이미 인정된 서명에서 읽음) 버전에 published-at 참조자가 전혀 없는 경우입니다. 서명하지 않는 push는 이후 버전에 어떤 서명이 첨부되었든 서명되지 않은 게시와 마찬가지로 날짜가 필요합니다. 기재되는 날짜는 이 push 자신의 시계, 즉 게시가 완료된 시각이며, 레지스트리가 제공하는 어떤 것도 콘텐츠가 처음 도착한 순간을 기록하지 않으므로 그 시각보다 늦습니다.

이미 완료된 게시는 push를 몇 번 반복하든 아무것도 첨부되지 않습니다. push는 무언가를 첨부하기 전에 버전에 있는 서명과 날짜를 읽고, 필요한 서명을 만듭니다. 답할 수 없는 질문(읽을 수 없는 목록이나 서명, 또는 신뢰 루트를 얻을 수 없어 판단할 수 없는 서명)과 만들 수 없는 서명은 버전에 아무것도 없다는 의미로 간주되지 않고, 각각 아무것도 첨부하지 않은 채 0이 아닌 코드로 종료합니다.

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

push는 레지스트리에 단계별로 씁니다. 먼저 콘텐츠(Plugin의 경우 엔티티와 그 .wasm), 다음으로 그것을 가리키는 매니페스트, 그다음 버전 태그, 마지막으로 그 옆에 서명과 게시 날짜를 씁니다. 쓰기를 수행하는 각 단계는 이후 시도에서 성공할 수 있는 방식으로 실패하면 재시도됩니다. 레지스트리가 서버 오류(Retry-After를 포함한 503을 제외한 모든 5xx 상태) 또는 408 Request Timeout으로 응답하거나, 연결이 시간 초과되거나, 재설정되거나, 응답 도중에 끊어지는 경우입니다. 한 단계는 최대 세 번 시도되며, 두 번째 시도 전에 0.5초, 세 번째 시도 전에 1초를 기다립니다.

속도를 늦추라고 요청하는 레지스트리는 기다리며, 그 시도 횟수를 하나도 소모하지 않습니다. 429 Too Many Requests 또는 Retry-After를 포함한 503을 받으면 해당 레지스트리에 대한 모든 요청은 읽기든 쓰기든 레지스트리가 요청한 만큼 기다린 뒤 다시 전송되며, 콘텐츠가 거부된 단계는 새 업로드로 다시 시작됩니다. 정해진 시도 횟수는 없으며, 레지스트리가 5분 동안 “속도를 늦추라”는 응답만 할 때까지 계속됩니다. 대기와 그것을 끝내는 거부는 속도를 늦추라고 요청하는 레지스트리에서 설명합니다.

각 시도는 동일한 바이트를 새로 업로드하는 것이며, 실패한 요청을 다시 보내는 것이 아닙니다. 이미 업로드 본문을 받은 레지스트리는 같은 요청을 두 번째로 거부할 수 있으며, 레지스트리가 받아들이는 것은 새 업로드입니다. 레지스트리가 이미 보유한 콘텐츠는 업로드된 것으로 간주되고, 재시도된 단계는 첫 번째 시도가 썼을 내용을 그대로 쓰므로, 반영되었지만 응답이 유실된 시도가 있어도 아무것도 두 번 반영되지 않습니다. 매니페스트는 다이제스트를 유지하고, 버전에는 서명 하나와 게시 날짜 하나가 붙습니다.

그 밖의 모든 실패는 단계를 즉시 종료합니다. 거부된 자격 증명(401, 403 또는 해당 레지스트리에 대해 저장된 자격 증명이 없음), 레지스트리가 보내는 그 밖의 모든 응답, 전혀 연결할 수 없는 레지스트리, 사용자가 중단한 push가 이에 해당합니다. 마지막 시도 후에도 여전히 실패하는 단계는 명령을 실패시키며, 오류에는 해당 단계가 명시됩니다. 단계는 콘텐츠, 매니페스트, 태그, 서명 또는 게시 날짜입니다. 앞선 단계에서 게시된 것은 게시된 상태로 남습니다. 이것이 버전에 어떤 의미인지는 서명과 게시 날짜에서 설명합니다.

이러한 실패에 대해 재시도되는 것은 쓰기뿐입니다. 아무것도 업로드하기 전에 레지스트리가 해당 버전에 이미 보유한 내용을 읽는 작업은 재시도되지 않지만, 모든 요청과 마찬가지로 속도를 늦추라고 요청하는 레지스트리가 요청하는 만큼 기다립니다.

서명

aggrega push는 게시하면서 아티팩트에 서명하고, 그 서명을 OCI referrer로 첨부할 수 있습니다. 이는 아티팩트의 변경 불가능한 manifest 다이제스트에 대한 Sigstore(cosign 호환) 번들입니다. 서명은 형제 manifest이므로 서명이 게시된 바이트를 다시 푸시하거나 변경하는 일은 없습니다. referrer는 번들 이름을 signature.json으로 지정하므로, 일반 OCI 클라이언트가 다이제스트로 referrer를 가져오면 번들이 그 파일에 기록됩니다.

서명은 푸시 전 서명(sign-before-push) 방식입니다. manifest 다이제스트는 게시 전에 알 수 있으므로, aggrega push는 어떤 바이트도 레지스트리에 도달하기 전에 서명자를 구성하고 다이제스트에 서명합니다. 서명자를 구성할 수 없거나 서명에 실패하면 무엇이든 업로드되기 전에 푸시가 거부됩니다. 아무것도 게시되지 않으므로 서명 실패로 서명되지 않은 콘텐츠가 레지스트리에 남는 일은 없습니다. 거부하기 전에, 일시적으로 실패한 서명 호출(레지스트리 쓰기가 재시도되는 모든 실패, 또는 키리스 인증 기관이 신원 토큰을 처리할 수 없다고 보고하는 경우)은 같은 대기 시간으로 최대 세 번까지 다시 시도됩니다. 키리스 서명 호출 내부에서는 인증 기관, 투명성 로그 또는 타임스탬프 기관이 429 Too Many Requests나 서버 오류로 응답한 요청을 먼저 aggrega sign에서 설명하듯 해당 서비스로 다시 보냅니다.

서명은 콘텐츠가 올라간 뒤에 첨부되므로, 첨부에 실패하면 콘텐츠는 서명 없이 게시된 상태로 남습니다. 첨부는 쓰기이며 레지스트리가 쓰기에 실패하는 경우에서 설명하는 대로 재시도됩니다. 그래도 실패하면 명령은 첨부하지 못한 서명을 명시하며 0이 아닌 코드로 종료되고, 레지스트리가 서명을 요구하는 소비자는 서명이 첨부될 때까지 해당 버전을 거부합니다. 이전 푸시가 부분적으로 남긴 게시 완료하기에서 설명하는 대로 같은 푸시를 다시 실행하면 서명이 첨부됩니다. aggrega sign은 게시된 버전에 참조로 서명을 첨부합니다.

대상 레지스트리 자체의 signing 블록이 required: true를 설정하거나, 최상위 signing 블록이 모든 레지스트리에 대해 이를 설정하면 게시에는 서명이 필요합니다. 각각은 kinds가 종류를 나열한 경우 그 종류로 제한됩니다. 이러한 게시는 기본적으로 서명하며, --sign은 서명을 명시적으로 요청합니다. 서명이 필요한 곳에 서명되지 않은 콘텐츠를 푸시하는 플래그는 없으며, 그러한 푸시는 항상 중단됩니다.

두 가지 서명 모드:

  • 키리스(Keyless)(기본값) — 단기 Fulcio 인증서로 OIDC 신원에 바인딩된 임시 키이며, Rekor 투명성 로그에 기록됩니다. Fulcio와 Rekor는 기본적으로 공공 Sigstore 인스턴스(https://fulcio.sigstore.dev, https://rekor.sigstore.dev)를 사용합니다. 키리스의 신뢰할 수 있는 타임스탬프는 Rekor 투명성 로그 포함에서 얻으며, 별도의 RFC3161 타임스탬프 기관은 선택 사항입니다. 사용하려면 --timestamp-url에 전체 엔드포인트를 지정합니다. 대화형 터미널에서는 키리스 서명에 플래그가 필요 없습니다. CLI가 브라우저를 열어 단기 OIDC 신원 토큰을 획득합니다. GitHub Actions에서도 플래그가 필요 없습니다. CLI가 러너의 주변 엔드포인트에서 워크플로 OIDC 토큰을 자동으로 발급받습니다. 그 밖의 비대화형 / CI 환경에서는 AGGREGA_IDENTITY_TOKEN(또는 SIGSTORE_ID_TOKEN)을 export하거나 --identity-token을 전달합니다. 제공된 토큰, 주변 엔드포인트, 터미널이 모두 없으면 푸시가 거부됩니다. CI 토큰 모델은 environment-variables.md를 참조하십시오.
  • 키 기반(Keyed)(--key) — 오프라인으로 보관하는 ECDSA P-256 키(cosign 호환 PEM)로, OIDC 신원 공급자가 없는 환경을 위한 탈출구입니다. 신원 공급자, 인증 기관, 투명성 로그 어디에도 접속하지 않습니다.

키리스 서비스 URL과 키 기반 키 경로는 .aggrega-config.yaml의 signing: 블록(전역 및 레지스트리별)에서도 설정할 수 있습니다. 플래그는 구성을 재정의하고, 구성은 공공 기본값을 재정의합니다. OIDC 신원 토큰은 단기 비밀이므로 결코 구성 필드가 되지 않으며, 개인 키도 구성에 인라인으로 들어가지 않고 그 경로만 지정됩니다.

게시 날짜

manifest의 생성 시간은 고정되어 있으므로 manifest 다이제스트는 무엇이 게시되었는지에만 의존하며 언제 게시되었는지에는 의존하지 않습니다. 대신 버전이 게시된 날짜는 그 옆에 함께 전달되며, 그 출처는 서명에 따라 달라집니다.

  • 키리스 서명은 이미 날짜를 담고 있습니다. 서명의 투명성 로그 항목은 로그가 서명을 통합한 시각을 기록하며, 로그의 서명된 약속이 그 시각을 증명합니다. aggrega push는 아무것도 추가로 기록하지 않습니다.
  • 키 기반 서명이나 서명이 없는 경우에는 시각이 담기지 않습니다. 따라서 엔터티와 서명(있는 경우)이 반영된 후 aggrega push는 manifest에 작은 published-at referrer를 첨부합니다. 이 referrer는 일반 OCI 클라이언트를 위해 published-at.json이라는 이름을 가지며, 게시하는 머신 자체의 시계에서 읽은 초 단위 UTC의 RFC 3339 타임스탬프 하나를 담습니다. 이 referrer는 서명되지 않습니다. 이는 게시자의 진술이며, 읽는 쪽도 그렇게 기록합니다. Publication date attached: 줄이 이를 보고합니다.

서명과 마찬가지로 published-at referrer는 게시된 manifest를 다시 가리키는 형제 manifest이므로, 어떤 다이제스트도 바꾸지 않고 어떤 태그도 변경하지 않으며, 기존 버전 위에 게시할 때의 검사에도 영향을 주지 않습니다. 같은 콘텐츠를 다시 push하면 날짜가 없는 버전에만 자신의 시계 기준 날짜를 첨부합니다. 이전 push가 일부만 남긴 게시 완료하기를 참조하십시오. 날짜는 첨부를 처음 시도하기 전에 시계에서 한 번 읽으므로, 재시도된 첨부(레지스트리가 쓰기에 실패할 때 참조)도 같은 날짜를 기록합니다. 콘텐츠는 게시했지만 이러한 시도 후에도 날짜를 첨부하지 못한 push는 0이 아닌 코드로 종료되며 첨부되지 않은 항목을 알려 줍니다. aggrega registry update는 각 버전의 날짜를 두 출처 중 어디에서 왔는지와 함께 기록합니다.

오프라인

게시는 네트워크 왕복 작업이며 그렇지 않은 형태가 없으므로, 오프라인 모드 — 구성 파일의 최상위 offline 키, AGGREGA_OFFLINE 또는 --offline — 에서는 aggrega push가 엔터티를 읽기 전에 거부합니다. 거부 메시지는 세 가지 중 어느 것이 이 모드를 설정했는지 알려 주며, 이는 사용자가 입력한 것이 아니라 프로젝트에 커밋된 구성이 이 모드를 켰을 때 필요한 정보입니다.

--dry-run은 예외이며, 그 동작 때문에 예외입니다. 이 플래그는 번들을 계산하고, 게시할 참조와 그 게시가 만들어 낼 다이제스트를 출력하며, 레지스트리에는 전혀 접속하지 않습니다. 따라서 오프라인 모드와 충돌하는 것이 아니라 오프라인에서도 안전한 게시 형태이며, 이 모드에서도 계속 동작합니다. 단, 한 가지 제한이 있습니다. 원격 source:가 전체 형태로 작성된 Recipe 또는 FeatureRecipe는 고정값을 비교하기 위해 해당 소스를 가져오는데, 오프라인 모드에서는 이 가져오기가 자체 메시지와 함께 거부되므로, 그런 엔터티에 대한 드라이 런은 보증할 수 없는 번들을 보고하지 않고 그 지점에서 중단됩니다.

구성이 오프라인으로 설정된 작업 공간에서 한 번의 실행 동안 게시하려면 --offline=false를 전달합니다.

환경 변수

서명 입력값과 대상 레지스트리는 환경 변수로 지정할 수 있으며, 이 값은 .aggrega-config.yaml보다 우선하지만 플래그보다는 우선하지 않습니다:

  • AGGREGA_IDENTITY_TOKEN — 키리스 OIDC ID 토큰입니다(--identity-token에 대응하는 환경 변수). SIGSTORE_ID_TOKEN도 sigstore 생태계와의 상호 운용을 위한 별칭으로 인정되며, AGGREGA_IDENTITY_TOKEN과 GitHub Actions 환경의 엔드포인트보다 낮은 순위를 가집니다. 토큰은 구성 필드로 지정할 수 없습니다.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — 키리스 서비스 URL입니다.
  • AGGREGA_SIGNING_KEY_PATH — 키 기반 서명용 PEM 키를 가리키는 경로입니다(키 자료 자체는 아닙니다).
  • AGGREGA_DEFAULT_REGISTRY — --registry를 생략했을 때 사용하는 대상 레지스트리입니다.

우선순위는 플래그 > 환경 변수 > 구성 > 기본값입니다. 전체 목록과 우선순위 모델은 environment-variables.md를 참조하십시오.

인증

aggrega push는 aggrega pull과 같은 방식으로, 즉 Docker 자격 증명 구성과 그 구성이 지정하는 자격 증명 도우미에서 레지스트리 자격 증명을 읽습니다. 비공개 레지스트리로 푸시하기 전에 다른 도구가 필요 없는 aggrega login <registry> 또는 docker login <registry>를 실행하십시오. 그 구성을 어디에서 읽는지는 aggrega-pull.md를 참고하십시오.

참고 항목

  • ./aggrega-sign.md — 이미 게시된 아티팩트에 사후에 서명합니다(--sign의 게시 후 대응 기능).
  • ./aggrega-lint.md — push보다 먼저 실행해야 하는 게시 관문(--pre-publish)입니다.
  • ./aggrega-pull.md — push가 게시한 것을 해석하고 고정하는 소비 측입니다.
  • ./aggrega-serve.md — 데몬은 이와 동일한 게시를 aggrega/publishEntity에서 제공하므로 편집기는 세션을 벗어나지 않고 이를 실행할 수 있습니다. 요청이 이를 지정할 때만 실행되며, 참조, 게시된 다이제스트(드라이 런에서는 --dry-run이 출력하는 다이제스트), 호출이 어디까지 진행되었는지, 그리고 이 명령이 경고하는 항목을 windowsUnusableEntries로 응답합니다.
  • ./aggrega-mcp.md — 어시스턴트가 호출할 수 있는 publish-entity 도구로 제공되는 동일한 기능이며, 해당 항목을 windows_unusable_entries로 응답합니다. 이를 허용하기 전에 해당 페이지에서 허용에 관해 설명하는 내용을 읽으십시오.
  • ../../architecture/13-catalog-and-registry.md — 카탈로그, 레지스트리 및 OCI 미디어 타입 모델입니다.

개요

aggrega push <entity-path> [flags]

설명

Publish a single catalog entity to an OCI registry, where other workspaces
resolve 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 path
lowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Plugin
its metadata.pluginType, as a segment between <kind> and <metadata.name>. The
tag is the entity's own metadata.version. Run "aggrega push --list-kinds" for
the kinds this binary publishes, one per line and nothing else, so a script can
read it directly. Release and Manifest are deployment-side inputs rather than
catalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: an
entity 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 it
before it is bundled, and one that read refuses is refused here for the same
reason: a document that fails its kind's schema, a path naming content outside
the entity's own directory, which would not travel with the entity, or a schema
a 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 a
metadata.version that is not a semantic version is refused. Its .wasm must then
agree with the entity on what the plugin offers and on its version, and a .wasm
whose 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 build
from uncommitted changes are both cleared by building the plugin from a clean
checkout of the commit its release tag names, never by copying the version it
reports into the entity. A development version such as 1.0.0-3-g1a2b3c4, built
from 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 names
beside 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 Feature
imports — and nothing else in its directory. An entity that names nothing
publishes as its document, unchanged; one that names a file publishes as a
gzipped archive of the document and those files. A directory it names travels
with 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 link
among those files is refused rather than followed. A local source written as a
template names no one directory until a Release fills it in, so an entity with
one 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 Windows
cannot 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 a
part ending in a full stop or a space. On Windows, aggrega refuses to unpack
such a file, so a Windows workspace cannot use the version. The warning is
written to standard error on every platform, one line per file, the entity
document'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 entity
that names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the execute
bit included — in the checkout it is published from. The OCI manifest names the
digest of the published bytes, so "aggrega pull" refuses a download that does
not match it. The lockfile a pull writes records the entity by the digest of its
content — each file's path and its bytes — which is the digest a pull in the
author's own workspace records for the same entity in its catalog directory, so
a build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is made
over the manifest digest before any bytes reach the registry, so a failed
signing refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what is
published and never on when. Push states when it published beside the manifest
instead, as a small published-at attachment carrying this machine's clock, in
UTC to the second — unless the signature it attached already carries a time a
transparency log attests, as a keyless signature does. So a keyed or unsigned
publication writes one, and a keyless one does not. The attachment moves no
digest and changes no tag. "aggrega registry update" records the date, with
which 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.lock
beside 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 is
missing 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, to
have push run that same step first, so the lock it writes is part of what is
published; --pin-sources=false skips it for one run.

플래그

플래그기본값설명
--dry-runfalse레지스트리에 연결하지 않고 번들을 계산하여, 제안되는 :와 게시 시 생성될 다이제스트를 출력합니다. 고정 누락으로 게시가 거부될 엔터티는 여기서도 거부됩니다
--entity—게시할 엔터티 YAML의 경로입니다(위치 인수로 전달할 수도 있습니다)
--fulcio-url—키리스 서명에 사용할 Fulcio 인증 기관 URL입니다. 생략하면 공용 Fulcio 인스턴스를 사용합니다.
--identity-token—키리스 서명에 사용할 OIDC ID 토큰입니다. 대화형 터미널(브라우저 흐름으로 토큰을 획득합니다)과 GitHub Actions(워크플로 OIDC 토큰이 자동으로 발급됩니다)에서는 선택 사항입니다. 그 밖의 비대화형/CI 환경에서는 필수이며, 대신 AGGREGA_IDENTITY_TOKEN 또는 SIGSTORE_ID_TOKEN으로 내보낼 수도 있습니다.
--key—오프라인 키 기반 서명에 사용할, 보유 중인 ECDSA P-256 개인 키 PEM의 경로입니다. 생략하면 키리스 서명을 사용합니다.
--list-kindsfalse게시할 수 있는 모든 엔터티 종류를 나열한 뒤 아무것도 게시하지 않고 종료합니다. 출력은 기계가 읽을 수 있으며 형식은 안정적입니다. 한 줄에 하나의 종류가 정렬된 순서로 출력되며 그 밖의 내용은 없습니다.
--pin-sourcesfalse번들링하기 전에 엔터티에 대해 엔터티 작성자의 고정 단계를 실행하여, 이 단계가 엔터티 옆에 기록하는 entity.lock이 게시 대상에 포함되도록 합니다. 잠금 파일이 고정을 기록하지 않은 엔터티를 거부하는 대신입니다. aggrega pin과 동일한 단계이며 동일한 바이트를 기록합니다. 엔터티 옆에 기록하므로 엔터티에 쓰기 가능한 위치가 있는 경우, 즉 읽어 들인 디렉터리에 있는 문서인 경우에만 실행됩니다. push는 지정한 엔터티 문서를 게시하므로 항상 이 조건을 충족합니다. 워크스페이스의 pin_sources_at_push를 양방향으로 재정의합니다. 설정과 관계없이 —pin-sources는 이번 실행에서 고정하고 —pin-sources=false는 고정하지 않습니다
--plugin—Plugin 엔터티의 로컬 .wasm 아티팩트 경로입니다. Plugin을 게시할 때 필수입니다. publish는 .wasm 아티팩트를 푸시하고 콘텐츠 다이제스트를 계산한 뒤 엔터티를 푸시합니다.
--registry—대상 레지스트리 호스트입니다(워크스페이스의 default_registry를 재정의합니다)
--rekor-url—키리스 서명에 사용할 Rekor 투명성 로그 URL입니다. 생략하면 공용 Rekor 인스턴스를 사용합니다.
--signfalse게시된 아티팩트에 서명하고 서명을 OCI 리퍼러로 첨부합니다. 생략하면 대상 레지스트리의 정책에 따라 서명합니다.
--timestamp-url—키리스 서명에 사용할 선택적 RFC3161 타임스탬프 기관 URL입니다.