aggrega deprecate
Đính kèm một dấu hiệu ngừng hỗ trợ đã ký vào một artifact đã xuất bản
Cú pháp
aggrega deprecate <reference> [flags]Mô tả
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.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--from | — | Tệp lô (YAML, hoặc JSON như một tập con) có danh sách cấp cao nhất gắn một marker cho mỗi mục. Mỗi mục mang reference, severity và reason, cùng với replacement và message tùy chọn. Loại trừ lẫn nhau với một tham chiếu vị trí và với —severity, —reason, —replacement và —message. |
--fulcio-url | — | URL của cơ quan cấp chứng chỉ Fulcio để ký không cần khóa. Khi bỏ qua, phiên bản Fulcio công cộng sẽ được sử dụng. |
--identity-token | — | Token định danh OIDC để ký không cần khóa. Tùy chọn khi ở terminal tương tác (một luồng trình duyệt sẽ lấy token) và trên GitHub Actions (token OIDC của workflow được tạo tự động); bắt buộc cho các trường hợp không tương tác/CI khác, khi đó có thể export nó dưới dạng AGGREGA_IDENTITY_TOKEN hoặc SIGSTORE_ID_TOKEN. |
--key | — | Đường dẫn tới tệp PEM khóa riêng ECDSA P-256 đang giữ để ký có khóa ngoại tuyến. Khi bỏ qua, phương thức ký không cần khóa sẽ được sử dụng. |
--message | — | Thông điệp tùy chọn, được giữ lại cho mục đích kiểm toán và cho chẩn đoán lúc build được ghi lại; mặc định là —reason khi không được đặt. Bị từ chối khi đi cùng —from, vì các mục của nó mang thông điệp riêng. |
--reason | — | Lý do dễ đọc cho việc deprecate — vì sao nó bị deprecate và nên làm gì thay thế. Bắt buộc khi có một tham chiếu vị trí, trừ khi một lời nhắc tương tác cung cấp nó; bị từ chối khi đi cùng —from, vì các mục của nó mang lý do riêng. |
--rekor-url | — | URL của nhật ký minh bạch Rekor để ký không cần khóa. Khi bỏ qua, phiên bản Rekor công cộng sẽ được sử dụng. |
--replacement | — | Tham chiếu artifact tùy chọn thay thế cho artifact bị deprecate. Bị từ chối khi đi cùng —from, vì các mục của nó mang giá trị riêng. |
--severity | — | Mức độ deprecate: một trong warning, error, retracted. Bắt buộc khi có một tham chiếu vị trí, trừ khi một lời nhắc tương tác cung cấp nó; bị từ chối khi đi cùng —from, vì các mục của nó mang mức độ riêng. |
--timestamp-url | — | URL tùy chọn của cơ quan cấp dấu thời gian RFC3161 để ký không cần khóa. |
Nguồn gốc của các endpoint ký
URL Fulcio và Rekor cho việc ký không khóa và đường dẫn khóa cho việc ký bằng khóa cũng có thể đến từ khối signing: trong .aggrega-config.yaml (toàn cục và theo từng registry, trong đó giá trị đặt cho registry của artifact được ưu tiên hơn giá trị toàn cục, theo từng trường); cờ ghi đè cấu hình, và cấu hình ghi đè giá trị mặc định công cộng. Vì vậy, các instance công cộng được nêu trong bảng cờ chỉ được dùng khi cả cờ lẫn cấu hình workspace của bạn đều không chỉ định endpoint. Dấu đánh dấu được ký đúng như cách aggrega sign ký một artifact.
Khi registry làm một lần ghi thất bại
Việc deprecate một artifact ghi vào registry hai lần: marker, được gắn làm referrer của artifact, rồi đến chữ ký của marker, được gắn làm referrer của marker. Mỗi lần ghi được thử lại khi registry hoặc mạng làm nó thất bại theo cách mà một lần thử sau có thể thành công, chẳng hạn lỗi máy chủ, hết thời gian chờ hoặc kết nối bị đặt lại; aggrega push
liệt kê các lỗi đó. Một lần ghi được thử tối đa ba lần, cách nhau nửa giây rồi một giây, và mỗi lần thử là một lần tải lên mới của cùng các byte đó chứ không phải gửi lại yêu cầu đã thất bại. Dấu thời gian của marker được đóng một lần, trước lần thử đầu tiên, nên một lần ghi được thử lại để lại một marker và một chữ ký, không phải hai.
Việc ký marker, giữa hai lần ghi, không được thử lại toàn bộ; bên trong một lần ký keyless, một yêu cầu mà cơ quan cấp chứng chỉ, nhật ký minh bạch hoặc cơ quan dấu thời gian trả lời bằng 429 Too Many Requests hoặc lỗi máy chủ sẽ được gửi lại tới dịch vụ đó, như aggrega sign mô tả. Một lần ghi vẫn thất bại sau lần thử cuối cùng, hoặc một lần ký thất bại, sẽ dừng lệnh và nêu tên bước đó; một marker đã được gắn trước lúc đó vẫn được giữ nguyên mà không có chữ ký. Với --from, các mục đã được gắn trước mục bị thất bại vẫn được giữ nguyên.
Tệp lô mang nội dung của từng marker
Với --from, mức độ, lý do, thay thế và thông điệp của mỗi marker đến từ chính mục của nó trong tệp lô. Vì vậy, một --severity, --reason, --replacement hoặc --message được truyền cùng --from sẽ bị từ chối chứ không bị bỏ qua: lệnh nêu tên từng cờ đã truyền và dừng lại trước khi tệp lô được đọc, nên không marker nào được gắn. Hãy đặt nội dung vào các mục của tệp, hoặc deprecate một tham chiếu với các cờ nội dung của nó.
Một lô được ký bằng một thông tin xác thực
Với --from, mọi marker trong tệp lô đều được ký bằng cùng một thông tin xác thực:
một khóa duy nhất đang nắm giữ, hoặc một danh tính keyless duy nhất được yêu cầu một lần cho cả tệp.
Mục nào cần loại nào được quyết định bởi cấu hình cho registry của tham chiếu của mục đó
— một signing.key_path áp dụng cho registry đó sẽ chọn khóa mà nó
chỉ định, và khi không có cái nào áp dụng thì marker được ký keyless. Khi các mục sẽ
cần các thông tin xác thực khác nhau — cấu hình chỉ định một khóa cho một registry và
không chỉ định khóa nào cho registry khác, hoặc hai khóa khác nhau — sẽ không có marker nào được gắn và lệnh
nêu tên các registry ở mỗi bên. Lệnh làm điều đó trước khi yêu cầu bất kỳ danh tính nào và
trước khi đọc bất kỳ registry nào.
Hãy tách tệp thành mỗi lô cho một thông tin xác thực, hoặc truyền một khóa bằng --key, khóa này
áp dụng cho mọi mục bất kể cấu hình nói gì cho từng registry. Thông báo
được mô tả tại
References signed together need different signing credentials (Các tham chiếu được ký cùng nhau cần các thông tin xác thực ký khác nhau).
Bộ ký của mọi mục cũng được chuẩn bị trước khi gắn marker đầu tiên, vì vậy một khóa không đọc được, hoặc một identity token được cung cấp nhưng không mang subject dùng được, sẽ dừng lô mà không có gì được gắn.
Tác dụng của từng mức độ nghiêm trọng
Ba mức độ nghiêm trọng tạo thành một tập có thứ tự — warning, rồi error, rồi
retracted — và chúng chia thành hai tầng khác nhau ở thời điểm chúng tác động.
warning và error là các tầng mang tính khuyến nghị. Một dấu đánh dấu ở một trong hai mức này không bao giờ
thay đổi phiên bản mà một tham chiếu được phân giải tới. Nó được ghi lại khi bạn chạy
aggrega pull, và mọi bề mặt đọc lockfile đều báo cáo nó.
Mỗi bề mặt đó đều báo cáo mọi tham chiếu bị ngừng hỗ trợ mà lockfile ghim, bất kể mức độ nghiêm trọng, nêu tên tham chiếu, mức độ nghiêm trọng, thông điệp của nó, và thời điểm bản ghi được quan sát:
| Bề mặt | Cách nó xử lý một dấu đánh dấu đã được ghi lại |
|---|---|
aggrega build | Báo cáo nó, và dừng lại nếu bạn đã cấu hình dừng ở mức độ nghiêm trọng đó. |
aggrega validate --release | Báo cáo nó. Kết luận không thay đổi. |
aggrega lint --release | Báo cáo nó. Kết luận không thay đổi. |
aggrega serve | Công bố nó tới trình soạn thảo của bạn dưới dạng cảnh báo trong khi Aggregate đang mở. Một dấu đánh dấu chỉ định một tham chiếu hoặc một plugin chứ không phải một tài liệu trong không gian làm việc của bạn, nên nó nằm trên Aggregate; chỉ các lỗi ánh xạ của chính một Manifest mới được hiển thị trên Manifest. |
Công cụ build AI-native | Báo cáo nó, và từ chối nếu bạn đã cấu hình dừng ở mức độ nghiêm trọng đó. |
Các công cụ describe và validate AI-native | Báo cáo nó cùng với đầu ra của chính chúng. |
Việc một dấu đánh dấu có dừng một bản build hay không là một thiết lập riêng:
build.halt_on_deprecated_severity mặc định không được đặt, nên không có gì dừng lại, và
đặt nó thành một mức độ nghiêm trọng sẽ dừng ở mức đó trở lên. Nó chi phối bản build —
aggrega build và công cụ build AI-native, vốn là cùng một thao tác — và
không gì khác: các bề mặt báo cáo nêu tên dấu đánh dấu và vẫn tiếp tục trong mọi trường hợp.
Nâng ngưỡng không bao giờ làm giảm những gì bạn được thông báo, trên bất kỳ bề mặt nào — bạn vẫn
nhận được thông báo cho mọi thứ dưới ngưỡng đó, và cho mọi thứ mà việc dừng không
bao quát.
Một số plugin được ghi lại ở nơi khác, và các dấu đánh dấu của chúng đến từ đó. Một
phần gắn plugins.linter, và một phần gắn plugins.governance trong vai trò
ir-verdict hoặc render-verdict, không định hình phần nào của đầu ra được render, nên chúng
được ghim trong plugins-trust.yaml bên cạnh
lockfile thay vì trong chính lockfile. Mỗi bản ghi ở đó mang dấu đánh dấu
được phát hiện cho plugin mà nó nêu tên, cùng với danh tính của plugin, và aggrega pull
ghi lại dấu đó theo cùng cách nó ghi một dấu đánh dấu trên một dòng của lockfile.
aggrega build, aggrega lint --release và aggrega validate --release đọc
cả hai bản ghi, nên một plugin bị ngừng hỗ trợ được nêu tên ở đó giống như một tham chiếu bị ngừng hỗ trợ,
và build.halt_on_deprecated_severity chi phối cả hai như nhau. Có hai
điểm khác biệt đáng biết. Thông báo cho một plugin như vậy không nói bản ghi được quan sát
khi nào — tệp đó hoàn toàn không mang dấu thời gian, chính điều đó giúp
nó tái tạo giống hệt từng byte — nên thay vào đó nó nêu nguồn gốc của thông tin và lệnh
để làm mới nó. Và một mục ở đó không bao giờ bị ghi đè bởi một lần pull thông thường:
một dấu đánh dấu mới được công bố sẽ được thêm vào bản ghi mà plugin đã có,
trong khi danh tính mà nó bị ràng buộc vẫn giữ nguyên cho đến khi bạn yêu cầu thay đổi bằng
aggrega pull --upgrade.
retracted là tầng rút lại, và nó còn tác động sớm hơn. Một phiên bản
được ghi nhận là đã rút lại sẽ bị loại khỏi việc xem xét khi aggrega pull
chọn phiên bản cho một tham chiếu không nêu phiên bản. Nếu một phiên bản đã công bố khác
thỏa mãn tham chiếu, phiên bản đó được chọn và lệnh pull thông báo điều này,
nêu tên phiên bản đã bỏ qua, lý do được ghi nhận cho nó, và phiên bản đã
chọn thay thế. Nếu không còn phiên bản đã công bố nào thỏa mãn tham chiếu, lệnh pull
dừng lại và thông báo rằng mọi ứng viên đều đã bị rút lại — nó không báo cáo
thực thể là bị thiếu, và không bao giờ âm thầm chuyển sang phương án dự phòng.
Chỉ định rõ một phiên bản sẽ ghi đè việc thu hồi
Một tham chiếu chỉ định một phiên bản chính xác luôn phân giải tới đúng phiên bản đó, dù phiên bản ấy đã bị rút lại hay chưa. Việc chỉ định phiên bản chính là sự ghi đè, nên không có thiết lập riêng nào để tắt việc loại trừ — và một phiên bản đã được ghim từ lần
aggrega pull trước vẫn tiếp tục được phân giải vì đúng lý do đó.
Lệnh pull sẽ thông báo rõ ràng khi phiên bản bạn chỉ định đã bị thu hồi, để bản build đã cam kết với phiên bản đó vẫn tiếp tục hoạt động, trong khi bạn vẫn thấy được lý do vì sao mình có thể muốn chuyển sang phiên bản khác.
Bản ghi thu hồi là một ảnh chụp, không phải câu trả lời trực tiếp
Một artifact đã phát hành là bất biến, nhưng việc thu hồi thì không: một phiên bản có thể bị rút lại sau lần cuối bạn kiểm tra. Cơ chế loại trừ đọc những gì workspace của bạn đã ghi lại vào lần cuối nó xây dựng chỉ mục registry cục bộ, vì vậy nó bảo vệ bạn khỏi việc chọn một phiên bản được biết là đã bị thu hồi. Nó không thể cho bạn biết rằng một phiên bản hiện không bị thu hồi.
Mọi báo cáo về một marker được ghi lại trước đó đều nêu thời điểm bản ghi đó được quan sát, để
một bản ghi cũ có thể phân biệt được với một bản ghi mới, và mỗi báo cáo nêu tên lệnh
làm mới nó. Có hai bản ghi được lưu và chúng được làm mới riêng biệt: cơ chế loại trừ phiên bản
và aggrega inspect đọc chỉ mục registry cục bộ của bạn, được aggrega registry update
làm mới, còn aggrega build đọc marker được ghi trong lockfile, được
aggrega pull làm mới. Những gì aggrega pull in ra trong lúc đang tìm kiếm không mang
thời điểm như vậy — nó báo cáo những gì nó tìm thấy ngay lúc đó.
Cũng vì lý do đó, việc không có thu hồi nào không phải là bằng chứng rằng không có thu hồi nào tồn tại — chỉ là chưa có thu hồi nào được ghi lại vào lần cuối bạn làm mới.
Nơi bạn được thông báo
Lệnh nào thông báo cho bạn về một lần thu hồi phụ thuộc vào bản ghi mà lệnh đó đọc. Bảng ở phía trên đề cập đến dấu đánh dấu được ghi trong lockfile của bạn — những gì Release này đã ghim. Bảng này đề cập đến chỉ mục registry cục bộ — những gì một registry đã công bố — đó là bản ghi mà cơ chế loại trừ phiên bản đọc.
| Lệnh | Những gì lệnh cho bạn biết về một lần thu hồi đã được ghi nhận |
|---|---|
aggrega registry update | Nêu tên từng dấu đánh dấu mà lệnh gặp khi duyệt registry: kho lưu trữ, phiên bản mà dấu được ghi trên đó, mức độ nghiêm trọng, và liệu dấu đó đã được ghi nhận hay chưa. Sau đó, mỗi registry báo cáo số lượng dấu đánh dấu mà chỉ mục của nó hiện đang lưu giữ. |
aggrega search | Báo cáo phiên bản mà một lần phân giải sẽ chọn thay vì một phiên bản đã bị rút lại, và nêu tên các phiên bản đã bị rút lại trong cột NOTES. --include-retracted thay vào đó báo cáo phiên bản cao nhất đã được công bố. |
aggrega inspect | In mức độ nghiêm trọng đã ghi nhận bên dưới thực thể, cùng với phiên bản mà nó được ghi trên đó, lý do, phiên bản thay thế nếu có nêu tên, và ngày ban hành — cho mọi loại thực thể mà lệnh phân giải theo tên. |
aggrega pull | Nêu tên từng phiên bản bị bỏ qua, lý do được ghi nhận đối với phiên bản đó, và phiên bản được chọn thay thế. Một phiên bản bạn đã nêu tên rõ ràng vẫn được phân giải, và lần thu hồi được thông báo thay vì được thực thi. |
aggrega plugin add | Tương tự: một phiên bản mà lệnh chọn sẽ được sàng lọc trên bất kỳ con đường nào lệnh dùng để phân giải phiên bản, và một phiên bản bạn chỉ định dưới dạng <name>:<version> vẫn được phân giải, kèm thông báo về việc rút lại. Khi không thể đọc được các dấu đánh dấu, lệnh sẽ nói rõ điều đó và cho biết các phiên bản đã công bố chưa được sàng lọc. |
aggrega build | Không có gì từ bản ghi này. Lệnh chỉ đọc lockfile của bạn và không bao giờ đọc chỉ mục, vì vậy những gì nó báo cáo là dấu đánh dấu được ghi đối với phiên bản bạn đã ghim. |
aggrega serve | Không có gì từ bản ghi này. Quá trình phân giải riêng của nó không tham khảo các bản ghi thu hồi, nên một phiên bản đã bị rút lại vẫn có thể được chọn ở đó; nó công bố dấu đánh dấu của lockfile tới trình soạn thảo của bạn. |
Hãy đọc hai hàng cuối cùng cùng với phần còn lại: một lệnh chỉ thông báo cho bạn về một lần thu hồi khi nó đang làm điều gì đó mà lần thu hồi có liên quan — chọn một phiên bản, hoặc cho bạn thấy những gì một nhà phát hành đã nói. Sự im lặng từ một lệnh không làm cả hai việc đó không phải là bằng chứng rằng không có gì được ghi nhận.
Một thông báo nêu tên mức độ nghiêm trọng mà nhà phát hành đã ghi nhận. Một artifact đã bị rút lại được báo cáo là retracted; hai mức độ nghiêm trọng mang tính khuyến nghị được báo cáo là deprecated, có nêu rõ là mức nào trong hai mức. Vì vậy, những gì bạn đọc lại khớp với giá trị đã được soạn và giá trị mà bạn sẽ dùng để cấu hình ngưỡng dừng.
Hai loại thông báo được tách biệt vì chúng báo cáo các sự kiện khác nhau. Một dòng deprecation: cho bạn biết điều gì đó về một artifact. Một dòng retraction: cho bạn biết những gì bạn đã không nhận được — một phiên bản đã bị bỏ qua, hoặc một lần sàng lọc không thể thực hiện được. Khi một lệnh phát ra cả hai về cùng một artifact, đó là hai sự kiện chứ không phải một phát biểu được lặp lại hai lần.
Những lần phân giải mà việc loại trừ áp dụng
Việc loại trừ có tác dụng ở bất cứ đâu một lệnh chọn phiên bản thay cho bạn. Đó là quy tắc, và nó quyết định một lần phân giải cụ thể nào đó có được áp dụng hay không.
aggrega pull áp dụng nó ở bất cứ đâu lệnh này chọn phiên bản cho một tham chiếu không
chỉ định phiên bản — bất kể tham chiếu đó trỏ tới gì: một thực thể trong catalog, một thư viện, một
Aggregate đã được xuất bản. Một quy tắc duy nhất chi phối tất cả, nên phiên bản mà một tham chiếu
được phân giải tới không phụ thuộc vào loại tham chiếu đã yêu cầu nó.
aggrega plugin add áp dụng nó trên mọi con đường mà lệnh này dùng để phân giải một tham chiếu plugin
chưa ghim phiên bản: dựa trên các phiên bản đã xuất bản mà chỉ mục registry cục bộ của bạn đã có,
và dựa trên danh sách phiên bản trực tiếp mà lệnh tìm đến khi chỉ mục đó không
có repository. Một phiên bản đã bị rút sẽ bị bỏ qua, và việc thay thế được
thông báo, trên bất kỳ con đường nào đã phân giải nó.
Daemon phục vụ trình soạn thảo là ngoại lệ. Nó phân giải tham chiếu theo yêu cầu trong khi phục vụ một trình soạn thảo, và việc phân giải đó chọn phiên bản mà không tham khảo các bản ghi rút phiên bản, nên một phiên bản được ghi nhận là đã thu hồi vẫn có thể được chọn ở đó.
Ở nơi không có gì được chọn thì cũng không có gì để cơ chế loại trừ tác động: một tham chiếu
nêu một phiên bản chính xác sẽ phân giải đến đúng phiên bản đó, và việc thu hồi chỉ được thông báo
chứ không được thực thi. Tất cả những điều này cũng không thay đổi những gì bạn được thông báo lúc build —
aggrega build báo cáo mọi marker mà lockfile ghi lại, bất kể con đường nào đã ghim
phiên bản đó.
Xem thêm
- ./aggrega-sign.md — một marker được ký bằng chính digest của nó, nên các chế độ ký và thông tin xác thực mà mỗi chế độ cần là những gì được mô tả ở đó.
- ./aggrega-serve.md — daemon gắn cùng marker đó tại
aggrega/deprecateArtifact. Nội dung mà terminal nhắc bạn nhập là bắt buộc trong một yêu cầu ở đó, vì không có gì trên giao diện đó có thể hỏi bạn nội dung này. - ./aggrega-mcp.md — cùng khả năng này dưới dạng công cụ
deprecate-artifact, mà một trợ lý có thể gọi. Hãy đọc những gì trang đó nói về việc cho phép nó trước khi bạn làm vậy: một lần thu hồi thay đổi những gì mọi bên sử dụng registry đó phân giải được.