aggrega deprecate
이미 게시된 아티팩트에 서명된 지원 중단 표시 첨부
개요
aggrega deprecate <reference> [flags]설명
Deprecate amends an already-published artifact by attaching a deprecation marker to it as an OCI referrer, then signing that marker. It does not re-push, re-tag, or otherwise mutate the published bytes — the artifact is immutable; the marker is a sibling manifest pointing back at it, so a marker can be attached retroactively. The marker records a severity (warning, error, or retracted), a reason, an optional replacement reference, and the timestamp it was issued. Run it three ways: pass the content as flags; omit the content flags at an interactive terminal to be prompted for severity, reason, and replacement; or pass --from <file> to attach one marker per entry from a batch file, whose entries carry their own content, so a content flag passed beside --from is refused rather than ignored. The marker itself is signed the same way artifacts are: its manifest digest is signed and the signature is attached as a referrer of the marker, so the marker is verifiable the same way artifact signatures are. With --key the signature is produced offline from a held ECDSA P-256 key; without --key the keyless flow is used, which requires a live identity provider, Fulcio, and Rekor. Every marker of one --from batch is signed with one credential: where the configuration names a held key (signing.key_path) for one entry's registry and none for another's, or two different keys, no marker is attached and the command says to run one batch per credential.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--from | — | 최상위 목록의 항목마다 마커 하나를 첨부하는 배치 파일(YAML, 또는 그 부분집합인 JSON)입니다. 각 항목에는 reference, severity, reason이 들어 있으며, 선택적으로 replacement와 message를 추가할 수 있습니다. 위치 인수로 지정하는 참조 및 —severity, —reason, —replacement, —message와 함께 사용할 수 없습니다. |
--fulcio-url | — | 키리스 서명에 사용할 Fulcio 인증 기관 URL입니다. 생략하면 공용 Fulcio 인스턴스를 사용합니다. |
--identity-token | — | 키리스 서명에 사용할 OIDC ID 토큰입니다. 대화형 터미널(브라우저 흐름으로 토큰을 획득합니다)과 GitHub Actions(워크플로 OIDC 토큰이 자동으로 발급됩니다)에서는 선택 사항입니다. 그 밖의 비대화형/CI 환경에서는 필수이며, 대신 AGGREGA_IDENTITY_TOKEN 또는 SIGSTORE_ID_TOKEN으로 내보낼 수도 있습니다. |
--key | — | 오프라인 키 기반 서명에 사용할, 보유 중인 ECDSA P-256 개인 키 PEM의 경로입니다. 생략하면 키리스 서명을 사용합니다. |
--message | — | 감사 및 기록된 빌드 시점 진단을 위해 보존되는 선택적 메시지입니다. 설정하지 않으면 —reason의 값이 기본값이 됩니다. 항목마다 자체 메시지를 지니는 —from과 함께 지정하면 거부됩니다. |
--reason | — | 사람이 읽을 수 있는 지원 중단 사유로, 지원이 중단된 이유와 대신 해야 할 일을 설명합니다. 위치 인수로 참조를 지정할 때는 대화형 프롬프트로 제공하지 않는 한 필수이며, 항목마다 자체 사유를 지니는 —from과 함께 지정하면 거부됩니다. |
--rekor-url | — | 키리스 서명에 사용할 Rekor 투명성 로그 URL입니다. 생략하면 공용 Rekor 인스턴스를 사용합니다. |
--replacement | — | 지원이 중단된 아티팩트를 대체하는 선택적 아티팩트 참조입니다. 항목마다 자체 대체 항목을 지니는 —from과 함께 지정하면 거부됩니다. |
--severity | — | 지원 중단 심각도로, warning, error, retracted 중 하나입니다. 위치 인수로 참조를 지정할 때는 대화형 프롬프트로 제공하지 않는 한 필수이며, 항목마다 자체 심각도를 지니는 —from과 함께 지정하면 거부됩니다. |
--timestamp-url | — | 키리스 서명에 사용할 선택적 RFC3161 타임스탬프 기관 URL입니다. |
서명 엔드포인트의 출처
키 없는 서명의 Fulcio 및 Rekor URL과 키 기반 서명의 키 경로는 .aggrega-config.yaml의 signing: 블록(전역 및 레지스트리별이며, 아티팩트의 레지스트리에 설정된 값이 필드별로 전역 값보다 우선합니다)에서 가져올 수도 있습니다. 플래그는 구성을 재정의하고, 구성은 공용 기본값을 재정의합니다. 따라서 플래그 표에 명시된 공용 인스턴스는 플래그와 워크스페이스 구성 모두 엔드포인트를 지정하지 않은 경우에만 사용됩니다. 마커는 aggrega sign이 아티팩트에 서명하는 것과 정확히 같은 방식으로 서명됩니다.
레지스트리가 쓰기에 실패하는 경우
아티팩트를 폐기 예정으로 지정하면 레지스트리에 두 번 씁니다. 먼저 마커를 아티팩트의 referrer로 첨부하고, 이어서 마커의 서명을 마커의 referrer로 첨부합니다. 각 쓰기는 서버 오류, 타임아웃, 연결 재설정처럼 이후 시도에서 성공할 수 있는 방식으로 레지스트리나 네트워크가 실패시킨 경우 재시도됩니다. 이러한 실패 목록은 aggrega push에 나와 있습니다. 쓰기는 최대 세 번 시도되며, 시도 간격은 처음에 0.5초, 그다음에 1초입니다. 각 시도는 실패한 요청을 다시 보내는 것이 아니라 같은 바이트를 새로 업로드하는 것입니다. 마커의 타임스탬프는 첫 시도 전에 한 번만 찍히므로, 재시도된 쓰기는 마커와 서명을 두 개가 아니라 하나씩만 남깁니다.
두 쓰기 사이에 이루어지는 마커 서명은 전체로서는 재시도되지 않습니다. 키리스 서명 내부에서는 인증 기관, 투명성 로그 또는 타임스탬프 기관이 429 Too Many Requests나 서버 오류로 응답한 요청을 aggrega sign에서 설명하듯 해당 서비스로 다시 보냅니다. 마지막 시도 후에도 실패하는 쓰기나 실패한 서명은 명령을 중단시키고 해당 단계를 알려 줍니다. 그때까지 이미 첨부된 마커는 서명 없이 첨부된 상태로 남습니다. --from을 사용한 경우, 실패한 항목보다 먼저 첨부된 항목은 첨부된 상태로 남습니다.
배치 파일에 각 마커의 내용이 담깁니다
--from을 사용하면 각 마커의 심각도, 사유, 대체 항목, 메시지는 배치 파일에 있는 그 마커 자체의 항목에서 가져옵니다. 따라서 --from과 함께 전달된 --severity, --reason, --replacement, --message는 무시되지 않고 거부됩니다. 명령은 전달된 각 플래그를 지명하고 배치 파일을 읽기 전에 중단하므로 마커는 하나도 첨부되지 않습니다. 내용을 파일의 항목에 넣거나, 내용 플래그와 함께 참조 하나를 지원 중단하십시오.
배치는 하나의 자격 증명으로 서명됩니다
--from을 사용하면 배치 파일의 모든 마커가 같은 자격 증명으로 서명됩니다.
즉, 보유한 단일 키 하나 또는 파일 전체에 대해 한 번만 요청하는 단일 키리스 ID 하나입니다.
각 항목에 어느 쪽이 필요한지는 해당 항목 참조의 레지스트리에 대한 구성이 결정합니다.
해당 레지스트리에 적용되는 signing.key_path가 있으면 그것이 지정하는 키가 선택되고,
적용되는 것이 없으면 마커는 키리스로 서명됩니다. 항목들이 서로 다른 자격 증명을
필요로 하는 경우, 즉 구성이 한 레지스트리에는 키를 지정하고 다른 레지스트리에는 지정하지 않거나
서로 다른 두 키를 지정하는 경우에는 어떤 마커도 첨부되지 않으며, 명령은 양쪽의
레지스트리를 명시합니다. 이 확인은 ID를 요청하기 전, 그리고 레지스트리를 읽기 전에 이루어집니다.
파일을 자격 증명별로 하나의 배치로 나누거나, --key로 키 하나를 전달합니다. 이 키는
각 레지스트리에 대한 구성 내용과 관계없이 모든 항목에 적용됩니다. 이
메시지는
References signed together need different signing credentials (함께 서명되는 참조에 서로 다른 서명 자격 증명이 필요함)에 설명되어 있습니다.
또한 모든 항목의 서명자는 첫 번째 마커가 첨부되기 전에 준비되므로, 읽을 수 없는 키나 사용 가능한 주체를 담고 있지 않은 제공된 ID 토큰이 있으면 아무것도 첨부되지 않은 상태로 배치가 중단됩니다.
각 심각도의 동작
세 가지 심각도는 warning, error, retracted 순서의 순서 집합을 이루며, 언제 작동하는지에 따라 두 단계로 나뉩니다.
warning과 error는 권고 단계입니다. 어느 심각도의 마커든 참조가 어떤 버전으로 해석되는지를 바꾸지 않습니다. 마커는
aggrega pull을 실행할 때 기록되며, 잠금 파일을 읽는 모든 곳에서 보고됩니다.
이러한 곳은 모두 심각도와 관계없이 잠금 파일이 고정한 모든 지원 중단 참조를 보고하며, 참조, 심각도, 메시지, 그리고 기록이 관찰된 시점을 표시합니다.
| 보고 위치 | 기록된 마커에 대한 동작 |
|---|---|
aggrega build | 보고하며, 해당 심각도에서 중단하도록 구성한 경우 중단합니다. |
aggrega validate --release | 보고합니다. 판정은 바뀌지 않습니다. |
aggrega lint --release | 보고합니다. 판정은 바뀌지 않습니다. |
aggrega serve | Aggregate가 열려 있는 동안 편집기에 경고로 게시합니다. 마커는 워크스페이스의 문서가 아니라 참조나 플러그인을 지목하므로 Aggregate에 남아 있으며, Manifest에는 Manifest 자체의 매핑 오류만 표시됩니다. |
AI 네이티브 build 도구 | 보고하며, 해당 심각도에서 중단하도록 구성한 경우 거부합니다. |
AI 네이티브 describe 및 validate 도구 | 자체 출력과 함께 보고합니다. |
마커가 빌드를 중단시키는지는 별도의 설정입니다.
build.halt_on_deprecated_severity는 기본적으로 설정되어 있지 않으므로 아무것도 중단되지 않으며,
이를 어떤 심각도로 설정하면 그 심각도 이상에서 중단됩니다. 이 설정은 빌드, 즉
aggrega build와 같은 작업인 AI 네이티브 빌드 도구만을 관장하며
그 밖의 것에는 영향을 주지 않습니다. 보고하는 곳들은 어느 경우든 마커를 표시하고 계속 진행합니다.
임계값을 높여도 어느 곳에서든 보고되는 내용은 줄어들지 않습니다. 임계값 아래의 모든 것과 중단이 다루지 않는
모든 것에 대해 여전히 알림을 받습니다.
일부 플러그인은 다른 곳에 기록되며, 그 마커도 그곳에서 옵니다.
plugins.linter 연결과 ir-verdict 또는 render-verdict 역할의 plugins.governance 연결은
렌더링된 출력에 아무런 영향을 주지 않으므로, 잠금 파일 자체가 아니라 잠금 파일 옆의
plugins-trust.yaml에 고정됩니다. 그곳의 각 기록은 지정한 플러그인에 대해
발견된 마커를 식별 정보와 함께 담고 있으며, aggrega pull은 잠금 파일 행의 마커를 기록하는 것과
같은 방식으로 이를 기록합니다.
aggrega build, aggrega lint --release, aggrega validate --release는
두 기록을 모두 읽으므로, 지원 중단된 플러그인도 지원 중단된 참조와 마찬가지로 표시되며,
build.halt_on_deprecated_severity는 둘 모두에 똑같이 적용됩니다. 알아 둘 만한 차이가
두 가지 있습니다. 이러한 플러그인에 대한 알림은 기록이 관찰된 시점을 말하지 않습니다. 그 파일에는
타임스탬프가 전혀 없으며, 그 덕분에 바이트 단위로 동일하게 재현됩니다. 대신 알림은 그 사실의 출처와
이를 갱신하는 명령을 표시합니다. 또한 그곳의 항목은 일반적인 pull로는 다시 작성되지 않습니다. 새로 게시된 마커는
플러그인이 이미 가진 기록에 추가되며, 고정된 식별 정보는
aggrega pull --upgrade로 변경을 요청할 때까지 그대로 유지됩니다.
retracted는 철회 단계이며, 더 이른 시점에도 작동합니다.
철회된 것으로 기록된 버전은 aggrega pull이 버전을 지정하지 않은 참조의 버전을 선택할 때
고려 대상에서 제외됩니다. 게시된 다른 버전이 참조를 충족하면 그 버전이 선택되고 pull은
건너뛴 버전, 그 버전에 기록된 사유, 대신 선택한 버전을 표시하며 이를 알립니다.
참조를 충족하는 게시된 버전이 남아 있지 않으면 pull은 중단되고 모든 후보가 철회되었다고 알립니다.
엔터티가 없다고 보고하지 않으며, 조용히 대체 버전으로 넘어가지도 않습니다.
버전을 명시적으로 지정하면 철회가 무시됩니다
정확한 버전을 지정한 참조는 해당 버전이 철회되었는지와 관계없이 항상 그 버전으로 해석됩니다. 버전을 지정하는 것 자체가 재정의이므로 제외를 끄는 별도의 설정은 없습니다. 이전 aggrega pull에서 고정된 버전이 계속 해석되는 것도 정확히 같은 이유입니다.
지정한 버전이 철회된 경우 pull은 이를 명확하게 알립니다. 따라서 이미 해당 버전을 사용하기로 한 빌드는 계속 동작하며, 동시에 다른 버전으로 옮겨야 할 수도 있는 이유를 확인할 수 있습니다.
철회 기록은 실시간 응답이 아니라 스냅샷입니다
게시된 아티팩트는 변경할 수 없지만, 철회는 그렇지 않습니다. 마지막으로 확인한 뒤에 버전이 취소될 수 있습니다. 제외 기능은 워크스페이스가 로컬 레지스트리 인덱스를 마지막으로 빌드할 때 기록한 내용을 읽으므로, 철회된 것으로 알려진 버전을 선택하지 않도록 보호해 줍니다. 버전이 지금 철회되지 않았다는 것을 알려 줄 수는 없습니다.
이전에 기록된 마커에 대한 모든 보고는 그 기록이 언제 관찰되었는지를 명시하므로, 오래된
기록을 새로운 기록과 구별할 수 있으며, 각 보고는 해당 기록을 갱신하는 명령을 알려 줍니다. 기록은 두 가지가 유지되며 각각 따로 갱신됩니다. 버전 제외와
aggrega inspect는 로컬 레지스트리 인덱스를 읽으며, 이 인덱스는 aggrega registry update가
갱신합니다. 반면 aggrega build는 lockfile에 기록된 마커를 읽으며, 이 마커는
aggrega pull이 갱신합니다. aggrega pull이 확인하는 동안 출력하는 내용에는 그러한
시점이 붙지 않습니다. 바로 그 순간에 발견한 것을 보고하기 때문입니다.
같은 이유로, 철회가 없다는 것은 철회가 존재하지 않는다는 증거가 아닙니다. 마지막으로 갱신했을 때 기록된 철회가 없었다는 뜻일 뿐입니다.
알림을 받는 위치
어떤 명령이 철회에 대해 알려 주는지는 그 명령이 어떤 기록을 읽는지에 따라 정해집니다. 앞의 표는 lockfile에 기록된 마커, 즉 이 Release가 고정한 내용을 다룹니다. 이 표는 로컬 레지스트리 인덱스, 즉 레지스트리가 게시한 내용을 다루며, 이것이 버전 제외가 읽는 기록입니다.
| 명령 | 기록된 철회에 대해 알려 주는 내용 |
|---|---|
aggrega registry update | 레지스트리를 순회하면서 만나는 각 마커에 대해 저장소, 마커가 기록된 버전, 심각도, 마커가 기록되었는지 여부를 표시합니다. 이어서 각 레지스트리는 자신의 인덱스가 현재 보유한 마커 수를 보고합니다. |
aggrega search | 철회된 버전 대신 해석이 선택할 버전을 보고하고, 철회된 버전은 NOTES 열에 표시합니다. --include-retracted를 사용하면 대신 게시된 가장 높은 버전을 보고합니다. |
aggrega inspect | 엔터티 아래에 기록된 심각도를 마커가 기록된 버전, 사유, 대체 항목(지정된 경우), 발행 날짜와 함께 출력합니다. 이름으로 해석하는 모든 종류에 대해 그렇습니다. |
aggrega pull | 건너뛴 각 버전과 그 버전에 기록된 사유, 대신 선택한 버전을 표시합니다. 명시적으로 지정한 버전은 그대로 해석되며, 철회는 적용되지 않고 알림으로만 표시됩니다. |
aggrega plugin add | 동일합니다. 선택하는 버전은 버전을 해석하는 두 경로 모두에서 검사되며, <name>:<version>으로 지정한 버전은 여전히 해석되고 철회가 공지됩니다. 마커를 읽을 수 없었던 경우에는 그 사실을 알리고 게시된 버전이 검사되지 않았음을 명시합니다. |
aggrega build | 이 기록에서는 아무것도 알려 주지 않습니다. lockfile만 읽고 인덱스는 전혀 읽지 않으므로, 보고하는 내용은 고정한 버전에 기록된 마커입니다. |
aggrega serve | 이 기록에서는 아무것도 알려 주지 않습니다. 자체 해석이 철회 기록을 참조하지 않으므로 그곳에서는 철회된 버전이 여전히 선택될 수 있으며, lockfile의 마커는 편집기에 전달합니다. |
마지막 두 행은 나머지와 함께 읽어야 합니다. 명령은 버전을 선택하거나 게시자가 밝힌 내용을 보여 주는 것처럼, 철회와 관련된 작업을 할 때에만 철회에 대해 알려 줍니다. 두 작업 중 어느 것도 하지 않는 명령이 아무것도 알리지 않는다고 해서 기록된 것이 없다는 증거가 되지는 않습니다.
알림에는 게시자가 기록한 심각도가 표시됩니다. 철회된 아티팩트는 retracted로 보고되고, 두 가지 권고 심각도는 deprecated로 보고되며 둘 중 어느 것인지 표시됩니다. 따라서 읽어 들이는 값은 작성된 값과 일치하며, 중단 임계값을 구성할 때 사용할 값과도 일치합니다.
두 종류의 알림은 서로 다른 사건을 보고하므로 구분됩니다. deprecation: 줄은 아티팩트에 관한 사실을 알려 줍니다. retraction: 줄은 받지 못한 것, 즉 건너뛴 버전이나 수행할 수 없었던 검사를 알려 줍니다. 한 명령이 같은 아티팩트에 대해 두 줄을 모두 출력한다면, 이는 같은 내용을 두 번 말한 것이 아니라 두 가지 사실입니다.
제외가 적용되는 해석
제외는 명령이 버전을 선택하는 모든 곳에서 작동합니다. 이것이 규칙이며, 특정 해석이 적용 대상인지는 이 규칙으로 결정됩니다.
aggrega pull은 버전을 지정하지 않은 참조에 대해 버전을 선택하는 모든 곳에서
제외를 적용합니다. 참조가 가리키는 대상이 카탈로그 엔터티든, 라이브러리든,
게시된 Aggregate든 마찬가지입니다. 이들 모두에 하나의 규칙이 적용되므로, 참조가
해석되는 버전은 어떤 종류의 참조가 요청했는지에 따라 달라지지 않습니다.
aggrega plugin add는 고정되지 않은 플러그인 참조를 해석하는 모든 경로에서
제외를 적용합니다. 즉, 로컬 레지스트리 인덱스에 이미 있는 게시된 버전을 대상으로
해석할 때와, 해당 인덱스에 리포지토리가 없어 실시간 버전 목록을 조회할 때 모두
적용합니다. 어느 경로로 해석되든 철회된 버전은 건너뛰고, 대체 사실을
알립니다.
에디터용 데몬은 예외입니다. 데몬은 에디터에 서비스를 제공하는 동안 필요할 때마다 참조를 해석하며, 이 해석은 철회 기록을 참조하지 않고 버전을 선택하므로, retracted로 기록된 버전이 여전히 선택될 수 있습니다.
아무것도 선택되지 않는 곳에서는 제외가 작용할 대상이 없습니다. 정확한 버전을
지정한 참조는 그 버전으로 해석되며, 철회는 적용되지 않고 알림으로만
표시됩니다. 또한 이 중 어느 것도 빌드 시점에 알림받는 내용을 바꾸지 않습니다.
aggrega build는 어떤 경로로 버전이 고정되었든 lockfile에 기록된 모든 마커를
보고합니다.
참고 항목
- ./aggrega-sign.md — 마커는 자체 다이제스트로 서명되므로, 서명 모드와 각 모드에 필요한 자격 증명은 해당 문서에서 설명하는 것과 같습니다.
- ./aggrega-serve.md — 데몬은 같은 마커를
aggrega/deprecateArtifact에서 첨부합니다. 터미널에서 입력을 요청받는 내용은 해당 요청에서 필수입니다. 그 인터페이스에서는 이를 물어볼 수단이 없기 때문입니다. - ./aggrega-mcp.md — 어시스턴트가 호출할 수 있는
deprecate-artifact도구로 제공되는 같은 기능입니다. 이를 허용하기 전에 해당 문서에서 허용에 관해 설명하는 내용을 읽어 보십시오. 철회는 해당 레지스트리의 모든 소비자가 해석하는 결과를 바꿉니다.