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 | — | トップレベルのリストのエントリーごとに 1 つのマーカーを付与するバッチファイル(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 がアーティファクトに署名するのとまったく同じ方法で署名されます。
レジストリが書き込みに失敗した場合
アーティファクトを非推奨にすると、レジストリへの書き込みが 2 回行われます。1 回目はアーティファクトの referrer として添付されるマーカー、2 回目はマーカーの referrer として添付されるマーカーの署名です。各書き込みは、サーバーエラー、タイムアウト、接続のリセットなど、後の試行で成功しうる形でレジストリまたはネットワークが失敗させた場合に再試行されます。これらの失敗は
aggrega push
に一覧されています。書き込みは最大 3 回試行され、間隔は 0.5 秒、次に 1 秒です。各試行は失敗したリクエストの再送ではなく、同じバイト列の新しいアップロードです。マーカーのタイムスタンプは最初の試行の前に一度だけ付与されるため、再試行された書き込みで残るのはマーカー 1 つと署名 1 つであり、2 つずつにはなりません。
2 回の書き込みの間に行われるマーカーの署名は、全体としては再試行されません。キーレス署名の内部では、認証局、透明性ログ、またはタイムスタンプ局が 429 Too Many Requests またはサーバーエラーで応答したリクエストは、aggrega sign で説明するとおり、そのサービスに再送されます。最後の試行の後も失敗している書き込み、または失敗した署名はコマンドを停止させ、そのステップを示します。その時点ですでに添付されたマーカーは、署名がないまま添付された状態で残ります。--from を指定した場合、失敗したエントリより前に添付されたエントリは添付されたまま残ります。
バッチファイルが各マーカーの内容を持つ
--from を使う場合、各マーカーの重大度、理由、置き換え先、メッセージは、バッチファイル内のそのマーカー自身のエントリーから取得されます。そのため、--from と併せて渡された --severity、--reason、--replacement、--message は無視されるのではなく拒否されます。コマンドは渡されたそれぞれのフラグを示し、バッチファイルを読み取る前に停止するため、マーカーは 1 つも付与されません。内容はファイルのエントリーに記述するか、内容のフラグを使って 1 つの参照を非推奨にしてください。
バッチは 1 つの認証情報で署名される
--from を指定すると、バッチファイル内のすべてのマーカーが同じ認証情報で署名されます。つまり、保持している単一の鍵か、ファイル全体に対して一度だけ要求される単一のキーレス ID です。
各エントリにどちらが必要かは、その参照のレジストリに対する設定によって決まります。そのレジストリに適用される signing.key_path があればそこで指定された鍵が選択され、
適用されるものがなければマーカーはキーレスで署名されます。エントリごとに異なる認証情報が必要になる場合、つまり設定があるレジストリには鍵を指定し、
別のレジストリには指定していない場合や、2 つの異なる鍵を指定している場合は、マーカーは一切付与されず、コマンドは双方のレジストリを示します。
これは、ID が要求される前、かつどのレジストリも読み取られる前に行われます。
ファイルを認証情報ごとに 1 つのバッチに分割するか、--key で鍵を 1 つ渡してください。この鍵は、各レジストリに対する設定の内容にかかわらず、すべてのエントリに適用されます。
このメッセージについては
References signed together need different signing credentials(まとめて署名される参照に異なる署名用認証情報が必要です)で説明しています。
また、すべてのエントリの署名者は最初のマーカーが付与される前に準備されます。そのため、読み取れない鍵や、 使用可能なサブジェクトを持たない ID トークンが渡された場合は、何も付与されないままバッチが停止します。
各重大度の動作
3 つの重大度は順序付きの集合 ― warning、次に error、次に retracted ― を成し、いつ作用するかが異なる 2 つの段階に分かれます。
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 ネイティブの build ツール ― だけであり、それ以外には影響しません。報告を行う画面はいずれの場合もマーカーを示して処理を続けます。
しきい値を上げても、どの画面でも知らされる内容が減ることはありません。しきい値未満のもの、および停止の対象外のものすべてについて、引き続き通知を受け取ります。
一部のプラグインは別の場所に記録され、そのマーカーもそこから得られます。
plugins.linter のアタッチメント、および ir-verdict または render-verdict ロールの plugins.governance アタッチメントは、レンダリング出力にまったく影響しないため、ロックファイル自体ではなく、ロックファイルの隣の plugins-trust.yaml に固定されます。そこにある各レコードは、名前を示すプラグインについて検出されたマーカーをその ID と併せて保持し、aggrega pull はロックファイルの行にマーカーを記録するのと同じ方法でそれを記録します。
aggrega build、aggrega lint --release、aggrega validate --release は両方のレコードを読むため、非推奨のプラグインも非推奨の参照と同様にそこで示され、build.halt_on_deprecated_severity は両方を同じように制御します。知っておくべき違いが 2 つあります。そのようなプラグインの通知は、レコードが観測された時点を示しません ― そのファイルはタイムスタンプを一切持たず、それによってバイト単位で再現可能になっています ― そのため代わりに、情報の出所と、それを更新するコマンドを示します。また、そこにあるエントリは通常の pull で書き換えられることはありません。新たに公開されたマーカーはプラグインの既存のレコードに追加されますが、固定されている ID は、aggrega pull --upgrade で変更を求めるまでそのまま維持されます。
retracted は撤回の段階であり、より早い時点でも作用します。撤回として記録されたバージョンは、バージョンを指定していない参照に対して aggrega pull がバージョンを選ぶ際、検討対象から除外されます。別の公開済みバージョンが参照を満たす場合はそのバージョンが採用され、pull はその旨を、スキップしたバージョン、それに対して記録された理由、代わりに採用したバージョンを示して伝えます。参照を満たす公開済みバージョンが残っていない場合、pull は停止し、すべての候補が撤回されていることを伝えます。エンティティが見つからないとは報告せず、黙ってフォールバックすることもありません。
バージョンを明示的に指定すると取り下げが上書きされる
正確なバージョンを指定した参照は、そのバージョンが取り下げられているかどうかにかかわらず、常にそのバージョンに解決されます。バージョンを指定することそのものが上書きであるため、除外を無効にする別の設定はありません。また、以前の
aggrega pull で固定されたバージョンが引き続き解決されるのも、まったく同じ理由によります。
指定したバージョンが取り下げられている場合、pull はその旨を明示的に伝えます。そのため、すでにそのバージョンに依存しているビルドは引き続き動作し、同時に移行を検討すべき理由も確認できます。
撤回の記録はスナップショットであり、現時点の回答ではない
公開されたアーティファクトは不変ですが、撤回はそうではありません。最後に確認した後でバージョンが撤回されることがあります。除外は、ワークスペースが最後にローカルのレジストリインデックスを構築したときに記録した内容を読み取るため、撤回済みであることが分かっているバージョンを選択することは防げます。あるバージョンが現時点で撤回されていないことを示すことはできません。
以前に記録されたマーカーの報告にはすべて、その記録がいつ観測されたかが示されるため、古い記録と新しい記録を区別できます。また、それぞれの報告には記録を更新するコマンドも示されます。記録は 2 つ保持され、それぞれ別々に更新されます。バージョンの除外と aggrega inspect はローカルのレジストリインデックスを読み取り、これは aggrega registry update が更新します。一方、aggrega build はロックファイルに記録されたマーカーを読み取り、これは 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 のマーカーはエディタに公開します。 |
最後の 2 行はほかの行と合わせて読んでください。コマンドが取り下げについて通知するのは、バージョンを選ぶ、または公開者が述べた内容を表示するといった、取り下げが関係する処理を行っている場合に限られます。どちらも行わないコマンドが何も示さないことは、何も記録されていないことの証拠にはなりません。
通知には公開者が記録した重大度が示されます。撤回されたアーティファクトは retracted として報告され、2 つの勧告的な重大度は deprecated として、そのどちらであるかを示して報告されます。そのため、読み取られる値は、作成された値および停止しきい値の設定に使う値と一致します。
2 種類の通知は異なる事象を報告するため、区別されています。deprecation: 行はアーティファクトについての情報を伝えます。retraction: 行は、得られなかったもの、つまりスキップされたバージョンや実行できなかった選別を伝えます。1 つのコマンドが同じアーティファクトについて両方を出力する場合、それは同じ内容を 2 回述べたものではなく、2 つの別個の事実です。
除外の対象となる解決
除外は、コマンドがバージョンを選択するすべての箇所で作用します。これが規則であり、特定の解決が対象となるかどうかはこれで決まります。
aggrega pull は、バージョンを指定していない参照に対してバージョンを選択するすべての箇所でこれを適用します。参照が指すものがカタログのエンティティ、ライブラリ、公開された Aggregate のいずれであっても同じです。
すべてに 1 つの規則が適用されるため、参照が解決されるバージョンは、どの種類の参照が要求したかに依存しません。
aggrega plugin add は、バージョンが固定されていないプラグイン参照を解決するすべての経路でこれを適用します。ローカルのレジストリインデックスがすでに保持している公開バージョンに対する解決と、そのインデックスがリポジトリを保持していない場合に参照するライブなバージョン一覧に対する解決の両方です。
どの経路で解決された場合でも、取り下げられたバージョンはスキップされ、その置き換えが通知されます。
エディタ向けのデーモンは例外です。デーモンはエディタにサービスを提供する間、必要に応じて参照を解決しますが、その解決は取り下げの記録を参照せずにバージョンを選択します。そのため、retracted として記録されたバージョンがそこでは選択される場合があります。
何も選択されない場合、除外が作用する対象はありません。正確なバージョンを指定した参照は
そのバージョンに解決され、取り下げは作用せずに通知されるだけです。また、これらはいずれもビルド時に通知される内容を変えません。
aggrega build は、どの経路でバージョンが固定されたかにかかわらず、ロックファイルに記録されたすべてのマーカーを報告します。
関連項目
- ./aggrega-sign.md — マーカーはそれ自身のダイジェストによって署名されるため、署名モードと それぞれに必要な認証情報は、そこで説明されているものと同じです。
- ./aggrega-serve.md — デーモンは同じマーカーを
aggrega/deprecateArtifactで付与します。ターミナルで入力を求められる内容は、そこではリクエストに必須です。 そのインターフェースには、それを尋ねる手段がないためです。 - ./aggrega-mcp.md — 同じ機能を、アシスタントが呼び出せる
deprecate-artifactツールとして提供します。 許可する前に、そのページで許可について説明されている内容を読んでください。取り下げは、 そのレジストリのすべての利用者が解決する内容を変更します。