跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

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 身份令牌。在交互式终端中(通过浏览器流程获取令牌)和在 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)附加;再写入标记的签名,作为该标记的引用方附加。当注册表或网络以一种后续尝试可能成功的方式导致写入失败时,例如服务器错误、超时或连接重置,该写入会被重试;aggrega push 列出了这些失败。每次写入最多尝试三次,间隔依次为半秒和一秒,每次尝试都是重新上传相同的字节,而不是重发失败的请求。标记的时间戳在第一次尝试之前只生成一次,因此重试的写入只会留下一个标记和一个签名,而不是两个。

在两次写入之间对标记进行签名的步骤不会作为整体重试;在无密钥签名内部,证书颁发机构、透明日志或时间戳机构以 429 Too Many Requests 或服务器错误应答的请求会再次发送给该服务,如 aggrega sign 所述。写入在最后一次尝试后仍然失败,或签名失败,都会停止命令并指出失败的步骤;此时已经附加的标记会保持附加状态,但没有签名。使用 --from 时,在失败条目之前已附加的条目会保持附加状态。

批处理文件承载每个标记的内容

使用 --from 时,每个标记的严重级别、原因、替代项和消息都来自批处理文件中它自己的条目。因此,与 --from 一起传入的 --severity、--reason、--replacement 或 --message 会被拒绝,而不是被忽略:命令会列出传入的每一个标志,并在读取批处理文件之前停止,因此不会附加任何标记。请把内容写进文件的条目中,或者使用内容标志弃用单个引用。

一个批次使用同一个凭据签名

使用 --from 时,批次文件中的每个标记都使用同一个凭据签名: 单个持有的密钥,或为整个文件只请求一次的单个无密钥身份。 某个条目需要哪一种,由其引用所在 registry 的配置决定——适用于该 registry 的 signing.key_path 会选中它指定的密钥, 没有适用的配置时,标记以无密钥方式签名。当各条目需要不同的凭据时——配置为一个 registry 指定了密钥而另一个没有, 或指定了两个不同的密钥——不会附加任何标记,命令会列出两边各自的 registry。 这一检查发生在请求任何身份之前,也发生在读取任何 registry 之前。

可以把文件拆分为每个凭据一个批次,或者用 --key 传入一个密钥, 它适用于每个条目,无论配置对各个 registry 如何规定。该消息的说明见 References signed together need different signing credentials(一起签名的引用需要不同的签名凭据)。

每个条目的签名者也会在附加第一个标记之前准备好,因此无法读取的密钥, 或所提供的身份令牌不带可用的主体,都会使该批次在未附加任何内容的情况下停止。

各严重级别的作用

三个严重级别构成一个有序集合——warning,然后是 error,然后是 retracted——它们分为两个层级,区别在于何时起作用。

warning 和 error 是提示性层级。处于这两个严重级别之一的标记从不 改变引用解析到的版本。它在你运行 aggrega pull 时被记录,所有读取 lockfile 的界面都会报告它。

这些界面中的每一个都会报告 lockfile 固定的每一个已弃用引用, 无论严重级别如何,并给出该引用、其严重级别、其消息,以及 该记录被观察到的时间:

界面对已记录标记的处理
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 原生的 build 工具,二者是同一操作—— 不控制其他任何东西:报告类界面无论如何都会指出该标记并继续执行。 提高阈值在任何界面上都不会减少你得到的信息——低于阈值的一切, 以及中止未覆盖的一切,你仍会收到通知。

有些插件记录在别处,其标记也来自那里。 plugins.linter 挂载,以及处于 ir-verdict 或 render-verdict 角色的 plugins.governance 挂载,不影响任何渲染输出,因此它们 固定在 lockfile 旁的 plugins-trust.yaml 中, 而不是 lockfile 本身。那里的每条记录都带有为其所指插件发现的标记, 以及该插件的身份;aggrega pull 记录它的方式与记录 lockfile 行上的标记相同。

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 读取锁文件中记录的标记,由 aggrega pull 刷新。aggrega pull 在查找过程中打印的内容不带有这样的时间点——它报告的是当时刚刚发现的内容。

出于同样的原因,没有撤回并不能证明撤回不存在——只能说明在你上次刷新时尚未记录任何撤回。

在哪里获知

哪个命令会告诉你撤回信息,取决于它读取的是哪份记录。前文的表格涵盖记录在 lockfile 中的标记,即该 Release 所固定的内容。本表涵盖本地 registry 索引,即 registry 所发布的内容,这也是版本排除所读取的记录。

命令它对已记录的撤回告诉你什么
aggrega registry update列出遍历 registry 时遇到的每个标记:仓库、标记所记录的版本、严重级别,以及该标记是否已被记录。随后每个 registry 报告其索引当前持有的标记数量。
aggrega search报告解析时会选取的版本,而不是已撤销的版本,并在 NOTES 列中列出已撤销的版本。使用 --include-retracted 时改为报告已发布的最高版本。
aggrega inspect在实体下方打印所记录的严重级别,以及其所记录的版本、原因、指定的替代项(如有)和发布日期,适用于它按名称解析的每一种类型。
aggrega pull列出它跳过的每个版本、针对该版本记录的原因,以及它改为选取的版本。你显式指定的版本仍会被解析,撤回只会被告知而不会被执行。
aggrega plugin add同上:它所选择的版本在它解析版本的任一途径上都会经过筛查,而你以 <name>:<version> 指定的版本仍会被解析,并公告其撤回。若无法读取标记,它会说明这一点,并声明已发布的版本未经筛查。
aggrega build不从这份记录中获取任何信息。它只读取你的 lockfile,从不读取索引,因此它报告的是针对你所固定的版本记录的标记。
aggrega serve不从这份记录中获取任何信息。它自身的解析不查询撤回记录,因此在那里仍可能选中已撤销的版本;它将 lockfile 中的标记发布给你的编辑器。

请将最后两行与其余各行结合起来阅读:命令只有在执行与撤回相关的操作时(选择版本,或向你展示发布者的声明)才会告诉你撤回信息。两者都不做的命令保持沉默,并不能证明没有任何记录。

通知会注明发布者记录的严重级别。已撤销的制品报告为 retracted;两种建议性严重级别报告为已弃用,并注明是其中哪一种。因此你读回的值与编写时的值一致,也与你配置中止阈值时所用的值一致。

两类通知被分开保留,因为它们报告的是不同的事件。deprecation: 行告诉你关于某个制品的信息。retraction: 行告诉你没有得到什么:一个被跳过的版本,或一次无法执行的筛查。当一个命令针对同一制品同时输出两者时,它们是两个事实,而不是同一陈述说了两遍。

排除覆盖哪些解析

只要命令为你选择一个版本,排除就会生效。这是 规则,它决定了任何特定的解析是否被覆盖。

aggrega pull 在为未指定版本的引用选择版本时都会应用它, 无论该引用指向什么:目录实体、库,还是已发布的 Aggregate。同一条规则适用于所有这些引用,因此引用 解析到的版本不取决于发出请求的是哪种引用。

aggrega plugin add 在解析未固定版本的插件引用的每条途径上都会应用它: 针对你的本地注册表索引中已有的已发布版本,以及当该索引中没有 该仓库时它所查询的实时版本列表。无论通过哪条途径解析,被撤回的版本都会被跳过, 并会通告这一替换。

面向编辑器的守护进程是例外。它在为编辑器提供服务时按需解析引用, 而这种解析在选择版本时不查询撤回记录,因此被记录为已撤回的版本在那里仍可能被选中。

没有进行选择的地方,排除也就无从作用:指定确切版本的引用 解析为该版本,撤回只会被提示, 而不会被执行。这些也都不会改变构建时告知你的内容—— 无论版本是经由哪条途径固定的,aggrega build 都会报告 lockfile 记录的每个标记。

另请参阅

  • ./aggrega-sign.md — 标记按其自身的摘要签名,因此签名模式 以及每种模式所需的凭据即为该页所述。
  • ./aggrega-serve.md — 守护进程在 aggrega/deprecateArtifact 处附加同样的标记。终端会提示输入的内容,在该处的请求中是必填的, 因为该接口上没有任何东西能够询问它。
  • ./aggrega-mcp.md — 以 deprecate-artifact 工具提供的同一能力, 助手可以调用它。在允许之前,请先阅读该页关于允许它的说明:一次撤回 会改变该 registry 的每个使用方解析到的结果。