aggrega deprecate
Melampirkan penanda deprekasi bertanda tangan ke artefak yang sudah dipublikasikan
Sinopsis
aggrega deprecate <reference> [flags]Deskripsi
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.Flag
| Flag | Default | Deskripsi |
|---|---|---|
--from | — | File batch (YAML, atau JSON sebagai subset) yang daftar tingkat atasnya melampirkan satu penanda per entri. Setiap entri memuat reference, severity, dan reason, ditambah replacement dan message opsional. Saling eksklusif dengan referensi posisional serta dengan —severity, —reason, —replacement, dan —message. |
--fulcio-url | — | URL otoritas sertifikat Fulcio untuk penandatanganan tanpa kunci. Jika dihilangkan, instans Fulcio publik digunakan. |
--identity-token | — | Token identitas OIDC untuk penandatanganan tanpa kunci. Opsional di terminal interaktif (alur browser memperolehnya) dan di GitHub Actions (token OIDC workflow diterbitkan secara otomatis); wajib untuk penggunaan non-interaktif/CI lainnya, yang memungkinkannya diekspor sebagai AGGREGA_IDENTITY_TOKEN atau SIGSTORE_ID_TOKEN sebagai gantinya. |
--key | — | Path ke PEM kunci privat ECDSA P-256 yang Anda miliki untuk penandatanganan berkunci secara offline. Jika dihilangkan, penandatanganan tanpa kunci digunakan. |
--message | — | Pesan opsional yang dipertahankan untuk audit dan untuk diagnostik waktu build yang tercatat; default-nya —reason jika tidak diatur. Ditolak jika disertai —from, yang entri-entrinya memuat pesannya sendiri. |
--reason | — | Alasan deprecation yang dapat dibaca manusia — mengapa ia di-deprecate dan apa yang harus dilakukan sebagai gantinya. Wajib bersama referensi posisional kecuali prompt interaktif menyediakannya; ditolak jika disertai —from, yang entri-entrinya memuat alasannya sendiri. |
--rekor-url | — | URL log transparansi Rekor untuk penandatanganan tanpa kunci. Jika dihilangkan, instans Rekor publik digunakan. |
--replacement | — | Referensi artefak opsional yang menggantikan artefak yang di-deprecate. Ditolak jika disertai —from, yang entri-entrinya memuat penggantinya sendiri. |
--severity | — | Tingkat keparahan deprecation: salah satu dari warning, error, retracted. Wajib bersama referensi posisional kecuali prompt interaktif menyediakannya; ditolak jika disertai —from, yang entri-entrinya memuat tingkat keparahannya sendiri. |
--timestamp-url | — | URL otoritas stempel waktu RFC3161 opsional untuk penandatanganan tanpa kunci. |
Asal endpoint penandatanganan
URL Fulcio dan Rekor untuk penandatanganan tanpa kunci serta path kunci untuk penandatanganan berkunci juga dapat berasal dari blok signing: di .aggrega-config.yaml (global dan per registry, dengan nilai yang ditetapkan untuk registry artefak lebih diutamakan daripada nilai global, per field); flag menimpa konfigurasi, dan konfigurasi menimpa default publik. Jadi instans publik yang disebut dalam tabel flag hanya digunakan jika baik flag maupun konfigurasi workspace Anda tidak menyebut endpoint. Penanda ditandatangani persis seperti aggrega sign menandatangani artefak.
Ketika registry menggagalkan penulisan
Men-deprecate artefak menulis ke registry dua kali: penanda, yang dilampirkan sebagai referrer artefak, lalu tanda tangan penanda, yang dilampirkan sebagai referrer penanda. Setiap penulisan dicoba ulang ketika registry atau jaringan menggagalkannya dengan cara yang memungkinkan percobaan berikutnya berhasil, seperti error server, timeout, atau koneksi yang di-reset; aggrega push mendaftar kegagalan tersebut. Penulisan dicoba paling banyak tiga kali, dengan jeda setengah detik lalu satu detik, dan setiap percobaan adalah unggahan baru dari byte yang sama, bukan pengiriman ulang permintaan yang gagal. Stempel waktu penanda dibubuhkan sekali, sebelum percobaan pertama, sehingga penulisan yang dicoba ulang meninggalkan satu penanda dan satu tanda tangan, bukan dua.
Penandatanganan penanda, di antara kedua penulisan, tidak dicoba ulang secara keseluruhan; di dalam penandatanganan keyless, permintaan yang dijawab otoritas sertifikat, log transparansi, atau otoritas stempel waktu dengan 429 Too Many Requests atau galat server dikirim lagi ke layanan tersebut, sebagaimana dijelaskan aggrega sign. Penulisan yang masih gagal setelah percobaan terakhirnya, atau penandatanganan yang gagal, menghentikan perintah dan menyebut langkahnya; penanda yang sudah terlampir pada saat itu tetap terlampir tanpa tanda tangannya. Dengan --from, entri yang dilampirkan sebelum entri yang gagal tetap terlampir.
File batch memuat konten setiap penanda
Dengan --from, tingkat keparahan, alasan, pengganti, dan pesan setiap penanda berasal dari entrinya sendiri di file batch. Karena itu, --severity, --reason, --replacement, atau --message yang diberikan bersama --from ditolak alih-alih diabaikan: perintah menyebutkan setiap flag yang diberikan dan berhenti sebelum file batch dibaca, sehingga tidak ada penanda yang dilampirkan. Letakkan konten di entri-entri file, atau deprecate satu referensi dengan flag kontennya.
Batch ditandatangani dengan satu kredensial
Dengan --from, setiap penanda dalam file batch ditandatangani dengan kredensial yang sama: satu kunci yang Anda miliki, atau satu identitas tanpa kunci yang diminta sekali untuk seluruh file. Mana yang dibutuhkan sebuah entri ditentukan oleh konfigurasi untuk registry referensinya — signing.key_path yang berlaku untuk registry tersebut memilih kunci yang disebutnya, dan jika tidak ada yang berlaku, penanda ditandatangani tanpa kunci. Ketika entri-entri akan membutuhkan kredensial yang berbeda — konfigurasi menyebut kunci untuk satu registry dan tidak untuk yang lain, atau dua kunci yang berbeda — tidak ada penanda yang dilampirkan dan perintah menyebut registry di masing-masing sisi. Hal ini dilakukan sebelum identitas apa pun diminta dan sebelum registry apa pun dibaca.
Pecah file menjadi satu batch per kredensial, atau berikan satu kunci dengan --key, yang berlaku untuk setiap entri apa pun yang dinyatakan konfigurasi untuk setiap registry. Pesan tersebut dijelaskan di References signed together need different signing credentials (Referensi yang ditandatangani bersama membutuhkan kredensial penandatanganan yang berbeda).
Penanda tangan setiap entri juga disiapkan sebelum penanda pertama dilampirkan, sehingga kunci yang tidak dapat dibaca, atau token identitas yang diberikan yang tidak memuat subject yang dapat digunakan, menghentikan batch tanpa ada yang terlampir.
Apa yang dilakukan setiap tingkat keparahan
Ketiga tingkat keparahan membentuk himpunan berurutan — warning, lalu error, lalu retracted — dan terbagi menjadi dua tingkatan yang berbeda dalam hal kapan keduanya bertindak.
warning dan error adalah tingkatan yang bersifat imbauan. Penanda dengan salah satu tingkat keparahan itu tidak pernah mengubah versi tujuan resolusi sebuah referensi. Penanda itu dicatat ketika Anda menjalankan aggrega pull, dan setiap permukaan yang membaca lockfile melaporkannya.
Setiap permukaan tersebut melaporkan setiap referensi yang di-deprecate yang di-pin lockfile, apa pun tingkat keparahannya, dengan menyebut referensi, tingkat keparahannya, pesannya, dan kapan catatan itu diamati:
| Permukaan | Apa yang dilakukannya dengan penanda yang tercatat |
|---|---|
aggrega build | Melaporkannya, dan berhenti jika Anda mengonfigurasi penghentian pada tingkat keparahan tersebut. |
aggrega validate --release | Melaporkannya. Putusannya tidak berubah. |
aggrega lint --release | Melaporkannya. Putusannya tidak berubah. |
aggrega serve | Menerbitkannya ke editor Anda sebagai peringatan selama Aggregate terbuka. Sebuah penanda menyebutkan referensi atau plugin, bukan dokumen di ruang kerja Anda, sehingga penanda tetap berada di Aggregate; hanya kesalahan pemetaan milik Manifest itu sendiri yang ditampilkan di Manifest. |
Alat build yang AI-native | Melaporkannya, dan menolak jika Anda mengonfigurasi penghentian pada tingkat keparahan tersebut. |
Alat describe dan validate yang AI-native | Melaporkannya bersama output mereka sendiri. |
Apakah penanda juga menghentikan build adalah pengaturan terpisah: build.halt_on_deprecated_severity tidak diatur secara default, sehingga tidak ada yang berhenti, dan mengaturnya ke suatu tingkat keparahan akan menghentikan build pada tingkat keparahan itu dan yang lebih tinggi. Pengaturan ini mengatur build — aggrega build dan alat build yang AI-native, yang merupakan operasi yang sama — dan tidak ada yang lain: permukaan pelaporan menyebut penanda dan tetap melanjutkan. Menaikkan ambang tidak pernah mengurangi apa yang diberitahukan kepada Anda, di permukaan mana pun — Anda tetap mendapat pemberitahuan untuk semua yang berada di bawahnya, dan untuk semua yang tidak dicakup penghentian.
Beberapa plugin dicatat di tempat lain, dan penandanya berasal dari sana. Lampiran plugins.linter, dan lampiran plugins.governance dalam peran ir-verdict atau render-verdict, tidak membentuk bagian apa pun dari output yang dirender, sehingga di-pin di plugins-trust.yaml di samping lockfile alih-alih di dalam lockfile itu sendiri. Setiap catatan di sana memuat penanda yang ditemukan untuk plugin yang disebutnya, di samping identitasnya, dan aggrega pull mencatatnya dengan cara yang sama seperti mencatat penanda pada baris lockfile.
aggrega build, aggrega lint --release, dan aggrega validate --release membaca kedua catatan, sehingga plugin yang di-deprecate disebut di sana sama seperti referensi yang di-deprecate, dan build.halt_on_deprecated_severity mengatur keduanya dengan cara yang sama. Ada dua perbedaan yang perlu diketahui. Pemberitahuan untuk plugin seperti itu tidak menyatakan kapan catatan itu diamati — file tersebut sama sekali tidak memuat stempel waktu, yang membuatnya dapat direproduksi byte demi byte — sehingga pemberitahuan itu menyebut asal fakta tersebut dan perintah yang menyegarkannya sebagai gantinya. Selain itu, entri di sana tidak pernah ditulis ulang oleh pull biasa: penanda yang baru diterbitkan ditambahkan ke catatan yang sudah dimiliki plugin, sementara identitas yang mengikatnya tetap tidak berubah hingga Anda memintanya diubah dengan aggrega pull --upgrade.
retracted adalah tingkatan penarikan, dan tingkatan ini juga bertindak lebih awal. Versi yang tercatat sebagai ditarik dikeluarkan dari pertimbangan ketika aggrega pull memilih versi untuk referensi yang tidak menyebut versi. Jika versi terbitan lain memenuhi referensi tersebut, versi itu yang diambil dan pull menyatakannya, dengan menyebut versi yang dilewatinya, alasan yang tercatat untuk versi itu, dan versi yang diambilnya sebagai gantinya. Jika tidak ada lagi versi terbitan yang memenuhi referensi, pull berhenti dan menyatakan bahwa setiap kandidat telah ditarik — pull tidak melaporkan entitas itu sebagai hilang, dan tidak pernah beralih ke versi lain secara diam-diam.
Menyebut versi secara eksplisit mengesampingkan penarikan
Referensi yang menyebut versi yang persis selalu di-resolve ke versi tersebut, baik versi itu sudah ditarik maupun belum. Menyebut versi adalah pengesampingannya, sehingga tidak ada pengaturan terpisah untuk menonaktifkan pengecualian — dan versi yang di-pin dari aggrega pull sebelumnya terus di-resolve karena alasan yang persis sama.
Pull menyatakannya secara terang-terangan ketika versi yang Anda sebut telah ditarik, sehingga build yang sudah berkomitmen padanya tetap berfungsi sementara Anda tetap dapat melihat mengapa Anda mungkin ingin beralih.
Catatan penarikan adalah snapshot, bukan jawaban langsung
Artefak yang diterbitkan tidak dapat diubah, tetapi penarikan dapat: sebuah versi dapat ditarik setelah terakhir kali Anda memeriksanya. Pengecualian membaca apa yang dicatat workspace Anda terakhir kali membangun indeks registry lokalnya, sehingga melindungi Anda dari memilih versi yang diketahui telah ditarik. Pengecualian tidak dapat memberi tahu Anda bahwa sebuah versi tidak sedang ditarik saat ini.
Setiap laporan tentang penanda yang dicatat sebelumnya menyatakan kapan catatan itu diamati, sehingga catatan yang usang dapat dibedakan dari yang baru, dan masing-masing menyebut perintah yang menyegarkannya. Dua catatan disimpan dan disegarkan secara terpisah: pengecualian versi dan aggrega inspect membaca indeks registry lokal Anda, yang disegarkan oleh aggrega registry update, sedangkan aggrega build membaca penanda yang dicatat di lockfile, yang disegarkan oleh aggrega pull. Apa yang dicetak aggrega pull saat mencari tidak membawa momen seperti itu — perintah itu melaporkan apa yang baru saja ditemukannya saat itu.
Dengan alasan yang sama, tidak adanya penarikan bukanlah bukti bahwa tidak ada penarikan — hanya bahwa belum ada yang dicatat saat terakhir kali Anda menyegarkan.
Tempat Anda diberi tahu
Perintah mana yang memberi tahu Anda tentang penarikan bergantung pada catatan mana yang dibacanya. Tabel di atas mencakup penanda yang tercatat di lockfile Anda — apa yang dipatok oleh Release ini. Tabel ini mencakup indeks registry lokal — apa yang diterbitkan oleh registry — yang merupakan catatan yang dibaca oleh pengecualian versi.
| Perintah | Apa yang diberitahukannya tentang penarikan yang tercatat |
|---|---|
aggrega registry update | Menyebutkan setiap penanda yang ditemuinya saat menelusuri registry: repositori, versi tempat penanda itu dicatat, tingkat keparahan, dan apakah penanda itu berhasil dicatat. Setiap registry kemudian melaporkan berapa banyak penanda yang kini dimuat indeksnya. |
aggrega search | Melaporkan versi yang akan diambil oleh resolusi alih-alih versi yang dicabut, dan menyebutkan versi-versi yang dicabut di kolom NOTES. --include-retracted justru melaporkan versi terbitan tertinggi. |
aggrega inspect | Mencetak tingkat keparahan yang tercatat di bawah entitas, beserta versi tempat tingkat itu dicatat, alasannya, penggantinya jika ada yang disebutkan, dan tanggal penerbitannya — untuk setiap jenis yang diresolusinya berdasarkan nama. |
aggrega pull | Menyebutkan setiap versi yang dilewatinya, alasan yang tercatat untuknya, dan versi yang diambil sebagai gantinya. Versi yang Anda sebutkan secara eksplisit tetap diresolusi, dan penarikannya diumumkan alih-alih diterapkan. |
aggrega plugin add | Sama: versi yang dipilihnya disaring pada kedua jalur yang digunakannya untuk meresolusi versi, dan versi yang Anda sebut sebagai <name>:<version> tetap teresolusi, dengan penarikannya diumumkan. Jika penanda tidak dapat dibaca, perintah ini menyatakannya dan menyebutkan bahwa versi-versi terbitan tidak disaring. |
aggrega build | Tidak ada dari catatan ini. Perintah ini hanya membaca lockfile Anda dan tidak pernah membaca indeks, sehingga yang dilaporkannya adalah penanda yang tercatat untuk versi yang Anda patok. |
aggrega serve | Tidak ada dari catatan ini. Resolusinya sendiri tidak memeriksa catatan penarikan, sehingga versi yang dicabut masih dapat dipilih di sana; perintah ini meneruskan penanda lockfile ke editor Anda. |
Bacalah dua baris terakhir bersama baris lainnya: sebuah perintah memberi tahu Anda tentang penarikan hanya ketika perintah itu melakukan sesuatu yang terpengaruh oleh penarikan — memilih versi, atau menunjukkan apa yang dinyatakan oleh penerbit. Diamnya perintah yang tidak melakukan keduanya bukanlah bukti bahwa tidak ada yang tercatat.
Sebuah pemberitahuan menyebutkan tingkat keparahan yang dicatat oleh penerbit. Artefak yang dicabut dilaporkan sebagai retracted; dua tingkat keparahan yang bersifat anjuran dilaporkan sebagai usang, dengan menyebutkan yang mana dari keduanya. Dengan begitu, apa yang Anda baca kembali sesuai dengan nilai yang ditulis dan nilai yang akan Anda gunakan untuk mengonfigurasi ambang penghentian.
Dua jenis pemberitahuan dipisahkan karena keduanya melaporkan peristiwa yang berbeda. Baris deprecation: memberi tahu Anda sesuatu tentang sebuah artefak. Baris retraction: memberi tahu Anda apa yang tidak Anda dapatkan — versi yang dilewati, atau penyaringan yang tidak dapat dilakukan. Jika satu perintah mengeluarkan keduanya tentang artefak yang sama, keduanya adalah dua fakta, bukan satu pernyataan yang disampaikan dua kali.
Resolusi mana yang dicakup pengecualian
Pengecualian berlaku di mana pun sebuah perintah memilih versi untuk Anda. Itulah aturannya, dan aturan itu menentukan apakah suatu resolusi tertentu tercakup.
aggrega pull menerapkannya di mana pun perintah ini memilih versi untuk referensi yang tidak menyebutkan versi — apa pun yang disebut referensi itu: entitas katalog, pustaka, atau Aggregate yang diterbitkan. Satu aturan mengatur semuanya, sehingga versi yang menjadi hasil resolusi sebuah referensi tidak bergantung pada jenis referensi yang memintanya.
aggrega plugin add menerapkannya pada setiap jalur yang digunakannya untuk meresolusi referensi plugin yang tidak dipatok: terhadap versi-versi terbitan yang sudah dimuat indeks registry lokal Anda, dan terhadap daftar versi langsung yang dijangkaunya ketika indeks itu tidak memuat repositori tersebut. Versi yang ditarik dilewati, dan penggantiannya diumumkan, pada jalur mana pun yang meresolusinya.
Daemon yang melayani editor adalah pengecualiannya. Daemon ini meresolusi referensi sesuai permintaan selama melayani editor, dan resolusi itu memilih versi tanpa memeriksa catatan penarikan, sehingga versi yang tercatat sebagai dicabut masih dapat dipilih di sana.
Jika tidak ada yang dipilih, tidak ada yang perlu ditindak oleh pengecualian: referensi yang menyebutkan versi persis diresolusi ke versi itu, dan penarikannya diumumkan alih-alih diterapkan. Semua ini juga tidak mengubah apa yang diberitahukan kepada Anda saat build — aggrega build melaporkan setiap penanda yang dicatat lockfile, apa pun jalur yang mematok versinya.
Lihat juga
- ./aggrega-sign.md — penanda ditandatangani berdasarkan digest-nya sendiri, sehingga mode penandatanganan dan kredensial yang dibutuhkan masing-masing adalah yang dijelaskan di sana.
- ./aggrega-serve.md — daemon melampirkan penanda yang sama di
aggrega/deprecateArtifact. Konten yang diminta di terminal wajib disertakan dalam permintaan di sana, karena tidak ada apa pun di antarmuka itu yang dapat memintanya. - ./aggrega-mcp.md — kemampuan yang sama sebagai alat
deprecate-artifact, yang dapat dipanggil oleh asisten. Bacalah apa yang dikatakan halaman itu tentang mengizinkannya sebelum Anda melakukannya: penarikan mengubah apa yang diresolusi oleh setiap konsumen registry tersebut.