aggrega push
aggrega push xuất bản một thực thể danh mục lên một OCI registry, nơi các workspace khác có thể phân giải nó bằng aggrega pull.
Chức năng
aggrega push đọc một tệp YAML thực thể duy nhất, đóng gói nó để vận chuyển và đẩy nó lên <registry>/<kind>/<metadata.name>:<metadata.version>, với đường dẫn repository được chuyển thành chữ thường; một Recipe hoặc FeatureRecipe mang spec.capability của nó, và một Plugin mang metadata.pluginType của nó, làm một đoạn nằm giữa kind và tên. Chạy aggrega push --list-kinds để xem các kind thực thể mà binary đã cài đặt có thể xuất bản — mỗi dòng một kind, đã sắp xếp, và không có gì khác, để một script có thể đọc trực tiếp. Tập hợp này bao gồm các kind soạn thảo catalog cùng với Aggregate, một module tái sử dụng được, và Plugin, một tham chiếu định địa chỉ theo nội dung tới một artifact WebAssembly mà trình biên dịch định tuyến và runtime thực thi. Plugin là một artifact có thể xuất bản mang tính cấu trúc chứ không phải một kind soạn thảo catalog. Khả năng xuất bản là thuộc tính của thực thể, không phụ thuộc vào cách nó được sử dụng: một Aggregate có thể xuất bản dù sau đó nó được tham chiếu làm spec.aggregate cấp cao nhất của một Release hay được lồng trong khối aggregates: của một Aggregate khác. Release và Manifest là các đầu vào phía triển khai, không phải artifact của catalog, và bị từ chối.
Đóng gói
Một lần push xuất bản tài liệu của thực thể và các tệp mà chính thực thể đó nêu tên bên cạnh nó — và không gì khác trong thư mục của nó. Các tệp mà một thực thể nêu tên là:
- đối với một Recipe hoặc FeatureRecipe,
source:cục bộ của nó — một thư mục được mang theo cùng mọi tệp bên dưới nó mà các quy tắc bỏ qua được ghi trongentity.lockcủa nó giữ lại, như Những tệp nào đi kèm một thực thể mô tả; mỗi tệp mà các mụcvaluesMapping:,workload:vàartifacts:của nó nhập bằng$import:; vàentity.lockbên cạnh nó; - đối với một Component hoặc Feature, mỗi tệp schema mà
spec.schema, một trụ cột hoặc một socketusesSchemacủa nó nhập bằng$import:, bao gồm mọi tệp mà một tệp được nhập lại nhập tiếp.
Một Aggregate, một Plugin và các kind thư viện không nêu tên tệp nào bên cạnh tài liệu của chúng. Một ghi chú, một README, các tệp của thực thể khác hoặc đầu ra của một bản build nằm trong thư mục sẽ không được xuất bản, bất kể tên của nó là gì. Một liên kết tượng trưng nằm trong số các tệp mà một thực thể nêu tên sẽ bị từ chối thay vì được đi theo — A symbolic link sits among the files an entity carries (Một liên kết tượng trưng nằm trong số các tệp mà một thực thể mang theo) — và một đường dẫn mà thực thể nêu tên qua một thư mục là liên kết dẫn ra ngoài thư mục của thực thể cũng vậy, trước khi bất cứ thứ gì được đóng gói — A path names content outside the entity’s own directory (Một đường dẫn trỏ tới nội dung bên ngoài thư mục riêng của thực thể).
Hình dạng xuất bản suy ra từ đó. Một thực thể không nêu tên gì được xuất bản dưới dạng tài liệu của nó, không thay đổi, với media type +yaml của kind đó. Một thực thể có nêu tên tệp được xuất bản dưới dạng một .tar.gz chứa tài liệu và các tệp đó ở đúng vị trí của chúng trong thư mục, với media type +tar+gz của kind đó. Vì vậy, một Recipe có toàn bộ nội dung nội tuyến được xuất bản dưới dạng tài liệu của nó, còn một Component có schema được nhập từ một tệp được xuất bản dưới dạng một kho lưu trữ. Catalog và Registry §6 liệt kê cả hai media type cho mọi kind.
Mỗi tệp trong kho lưu trữ mang mode 0644 và không có dấu thời gian, bất kể các bit quyền của nó trên đĩa. Một bản checkout ghi tệp với các bit quyền riêng, và một hệ thống không ghi nhận bit thực thi sẽ checkout thành tệp thường thứ mà hệ thống khác checkout thành tệp thực thi, nên kho lưu trữ không mang mode nào đọc từ đĩa: hai bản checkout của cùng một commit xuất bản cùng các tệp bất kể umask của chúng và bất kể chúng được tạo trên hệ thống nào, và việc đổi bit thực thi của một script không thay đổi gì trong những thứ được xuất bản.
Một lần push cảnh báo về mỗi mục trong kho lưu trữ mà Windows không thể lưu giữ như đã viết — một đường dẫn có một phần được đặt tên theo một thiết bị, như CON, AUX hoặc NUL, ở bất kỳ kiểu chữ hoa thường nào và bất kể phần mở rộng theo sau, như aux/x.yaml, hoặc một phần kết thúc bằng dấu chấm hoặc dấu cách, như report.. Trên Windows, aggrega từ chối giải nén một mục như vậy, nên một workspace Windows không thể dùng phiên bản đó. Cảnh báo được ghi ra standard error trên mọi nền tảng, mỗi mục một dòng, trước phần báo cáo của chính lần xuất bản; tên tệp của chính tài liệu thực thể được đánh giá cùng các tệp mà nó nêu tên, và một thực thể không nêu tên gì được xuất bản chỉ dưới dạng tài liệu của nó và không bao giờ bị cảnh báo. Cảnh báo không từ chối gì: lần push tiếp tục hoặc bị từ chối đúng như khi không có nó, và --dry-run cảnh báo theo cùng cách. A published archive carries an entry Windows cannot use (Một kho lưu trữ đã xuất bản chứa một mục mà Windows không thể dùng) cho thấy dòng cảnh báo và cách xử lý.
Một source: cục bộ được viết dưới dạng template mang theo toàn bộ thư mục. Một template như ./charts/{{ .values.flavour }} chỉ trỏ tới một thư mục khi một Release điền giá trị vào, nên không lần xuất bản nào có thể biết đó sẽ là thư mục nào. Một thực thể như vậy mang theo mọi tệp trong thư mục riêng của nó mà các quy tắc bỏ qua đã ghi nhận giữ lại — không bao giờ có .aggregaignore của nó, vốn có các quy tắc được mang trong lock — và lần push sẽ nói rõ điều đó bên dưới các thông tin khác của nó:
carries: every file in the entity's directory, because its source "./charts/{{ .values.flavour }}" is a template and the directory it names is decided by each Release that uses itThứ không được nêu tên thì không được mang theo, và người tiêu thụ mới là người phát hiện ra. Một tệp mà thực thể dựa vào nhưng không nêu tên qua một trong các trường trên sẽ không có trong bản xuất bản, và bản build của người tiêu thụ sẽ thất bại, nêu tên đường dẫn bị thiếu bên trong cache slot của nó — chứ không phải lần push của bạn. Hãy nêu tên mọi tệp mà thực thể cần qua một trong các trường đó.
Mỗi tệp được xuất bản đều được đặt tên trên manifest của artifact, nên một client OCI chung như oras ghi nó ra một tệp có tên đó: entity.yaml cho một thực thể được xuất bản dưới dạng tài liệu của nó, entity.tar.gz cho một thực thể được xuất bản cùng các tệp của nó, và với một Plugin thì entity.yaml cho thực thể bên cạnh entity.wasm cho tệp thực thi của nó. Tên được suy ra từ media type, không phải từ tệp mà bạn xuất bản, nên cùng một nội dung được xuất bản từ một tệp đã đổi tên sẽ xuất bản cùng một artifact. Catalog và Registry §6 liệt kê mọi hình dạng xuất bản và tên tệp tương ứng của mỗi hình dạng.
Một URL source: từ xa trên một Recipe (một tham chiếu chart OCI, một URL chart hoặc fragment HTTPS, một module Git) được giữ nguyên văn trong YAML đã xuất bản; nó không được kéo về và đưa vào artifact. Người tiêu thụ tự phân giải và ghim các nguồn từ xa một cách độc lập vào thời điểm pull của họ. Điều này giữ việc phân phối thực thể catalog và việc phân giải artifact nguồn là hai mối quan tâm tách biệt.
Một Aggregate được xuất bản dưới dạng một tài liệu duy nhất của riêng nó: một sub-aggregate mà nó tham chiếu trong aggregates: không được đóng gói vào artifact. Mỗi sub-aggregate là một Aggregate được xuất bản riêng, mà người tiêu thụ phân giải và ghim độc lập vào thời điểm pull, theo định danh — cùng nguyên tắc tách biệt phân phối áp dụng cho các nguồn từ xa.
Mỗi thư mục một thực thể
Một kho lưu trữ chứa tệp thực thể giữa các tệp mà nó nêu tên, nên khi giải nén ra thực thể phải được tìm lại. Bên tiêu thụ tìm thấy nó nhờ phần mở đầu mà nó mang: tài liệu ở đầu gói có kind: là một loại thực thể có thể xuất bản chính là thực thể. Tệp mà nó được viết trong đó có thể mang tên bất kỳ — recipe.yaml là quy ước của catalog chứ không phải một yêu cầu — và một đoạn compose, một mẫu chart hay một manifest Kubernetes nằm cạnh thực thể sẽ không bị nhầm là thực thể, vì chúng khai báo một thứ khác hoặc không khai báo kind nào cả. Các tài liệu thực thể nằm sâu hơn, bên trong một cây source/, là nội dung mà thực thể mang theo chứ không phải bản thân thực thể và không bao giờ được xét đến.
Một lần push từ chối một thực thể dùng chung thư mục với một thực thể khác. Mỗi kind có một thư mục riêng, trừ Aggregate, Release và Manifest, vốn được thư mục gốc của workspace chứa cạnh nhau. Với mọi kind khác, trước khi làm bất cứ điều gì khác với thực thể — trước bước pin, chính sách ký và gói — lệnh push kiểm tra rằng không có tài liệu thực thể nào khác nằm trong cùng thư mục, và nếu có thì từ chối, nêu tên từng thực thể gây cản trở, bất kể lệnh push có được yêu cầu pin hay không. aggrega pin từ chối cùng thư mục đó bằng cùng lời lẽ; điểm dừng là An entity shares its directory with another entity (Một thực thể dùng chung thư mục với một thực thể khác). Một tài liệu không thuộc loại thực thể nào nằm cạnh thực thể — một tệp chart, một đoạn compose, một README — không gây cản trở, và mọi thứ trong thư mục con cũng vậy. Mỗi tài liệu cạnh thực thể chỉ được đọc từ bên trong workspace, hoặc, với một thực thể bạn nêu tên bên ngoài nó, từ bên trong thư mục riêng của thực thể, nên một tài liệu là liên kết dẫn ra ngoài sẽ làm dừng lệnh push và nêu tên liên kết đó mà không đọc, như ranh giới workspace trình bày.
Quy định này là điều giữ cho một entity.lock thuộc về một thực thể: tên tệp của lock giống nhau cho mọi thực thể, nên hai thực thể được viết trong một thư mục sẽ phải dùng chung một lock duy nhất mà thư mục có chỗ chứa. Nó chỉ được xét khi có thứ gì đó được tạo ra từ thư mục, nên một thư mục chứa nhiều thực thể vẫn được tải, lint và build.
Tên của thư mục không được xét. Một thực thể nằm một mình trong thư mục của nó được xuất bản tại metadata.version của nó, bất kể thư mục đó nằm ở đâu; <name>/<version>/, bố cục mà catalog thư viện chuẩn tuân theo, là một quy ước. Một artifact mà client khác đã xuất bản từ một thư mục chứa hai thực thể vẫn được đọc an toàn: lệnh pull nó sẽ dừng và nêu tên cả hai tài liệu thay vì trả về một trong hai, được liệt kê tại errors/fatal-halts.md.
Đọc entity trước khi đóng gói
Một lần push đọc một Component, một Feature, một Recipe hoặc một FeatureRecipe theo cách một lần build đọc nó, và từ chối entity mà lần đọc đó từ chối — với cùng lý do, cùng mã ngắn, trước khi bundle được tạo và trước khi registry đích được liên hệ. Vì vậy, một tài liệu không đạt schema của kind của nó, một đường dẫn trỏ tới nội dung nằm ngoài thư mục riêng của entity, và một schema mà một Component hoặc Feature import bằng $import: nhưng bị thiếu hoặc không dùng được, đều bị từ chối ngay khi xuất bản thay vì được xuất bản. Mỗi trường hợp đó là một entity mà lần build đầu tiên của người dùng nó sẽ từ chối; một đường dẫn rời khỏi thư mục cũng trỏ tới một tệp sẽ không đi kèm entity, vì mọi tệp mà một bản xuất bản mang theo đều được lấy từ thư mục riêng của entity — xem A path names content outside the entity’s own directory (Một đường dẫn trỏ tới nội dung nằm ngoài thư mục riêng của entity).
Một Recipe hoặc FeatureRecipe được đọc theo cách này khi các pin của nó được so sánh, như phần tiếp theo mô tả, nên việc đọc diễn ra bất kể lần push có được yêu cầu pin hay không và bất kể entity có gì để pin hay không. Mỗi kind trong bốn kind này cũng được đọc theo cách này ngay trước khi bundle của nó được tạo, vì chính lần đọc đó cho biết nó trỏ tới những tệp nào. Một Aggregate và một thư viện không trỏ tới tệp nào và không được đọc theo cách này. Một Plugin cũng không trỏ tới tệp nào, và được đọc theo schema của kind của nó trước khi .wasm của nó được đọc, như Xuất bản một Plugin mô tả.
Xuất bản một Plugin
Một Plugin được xuất bản cùng với tệp .wasm của nó, do --plugin chỉ định, và lệnh push đánh giá cả hai trước khi bất kỳ byte nào được xuất bản hoặc registry được liên hệ. --dry-run đánh giá chúng đúng như một lần xuất bản.
Thực thể được đọc theo schema của loại của nó trước tiên, theo cách một lần tải catalog đọc nó, trước khi tệp .wasm được đọc. Vì vậy, một metadata.version không phải là phiên bản ngữ nghĩa — chẳng hạn một commit đơn thuần như 415148e — bị từ chối theo điều kiện riêng của schema, kèm tên trường, và mọi sai lệch khác so với schema cũng vậy, chẳng hạn thiếu spec.abiVersion. Điều được coi là phiên bản ngữ nghĩa ở đây là mẫu riêng của schema cho metadata.version; lệnh push không thêm quy tắc nào của riêng nó.
Sau đó tệp .wasm được nạp và đối chiếu với thực thể. Những gì nó báo cáo là cung cấp phải khớp với những gì thực thể khai báo, tập lệnh và các hàm host mà thực thể ghi lại phải khớp với nó, và phiên bản nó báo cáo về bản build của chính nó phải bằng metadata.version — xem A Plugin entity’s recorded version does not match the plugin (Phiên bản được ghi lại của một thực thể Plugin không khớp với plugin).
Một tệp .wasm được build từ cây làm việc có thay đổi chưa commit sẽ bị từ chối. Bản build như vậy mang dấu -dirty ở cuối phiên bản nó báo cáo — 1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty. Đó là một phiên bản ngữ nghĩa hợp lệ, nhưng nó chỉ đến một commit không chứa những gì đã được build, nên không ai có thể build lại những gì đã xuất bản từ phiên bản mà nó được xuất bản. Lệnh push từ chối nó, nêu tên phiên bản và cách khắc phục: build plugin từ một bản checkout sạch của commit mà tag của release chỉ đến, để nó báo cáo chính phiên bản release — và để phát hành thay đổi, hãy commit nó với metadata.version của thực thể được đặt thành release mới và tag commit đó trước — thay vì sao chép phiên bản mà một lần build lại báo cáo vào thực thể. Một phiên bản phát triển được build từ một commit, chẳng hạn 1.0.0-3-g1a2b3c4, và một bản phát hành trước như 1.0.0-rc.1 đều được xuất bản. Lỗi từ chối là A plugin was built from a working tree with uncommitted changes (Một plugin được build từ cây làm việc có thay đổi chưa commit).
Ghim trước khi xuất bản
Một Recipe hoặc FeatureRecipe mang các ghim (pin) cho những đầu vào mà nó đọc — một source: từ xa được viết đầy đủ, một tệp mà một mục artifacts nhập vào, các tệp của một source: nằm cạnh nó — trong tệp entity.lock nằm cạnh nó, và một lần push sẽ xuất bản tệp đó cùng với thực thể. Ghim là một bước bạn chạy trước khi xuất bản, aggrega pin, rồi commit tệp lock mà nó ghi ra.
Một lần push từ chối một thực thể có tệp lock không ghi lại các ghim đó. Trước khi dựng gói, lần push tính ra những gì bước ghim sẽ ghi lại cho thực thể và so sánh với tệp entity.lock nằm cạnh nó. Nếu thiếu một ghim, hoặc tệp lock giữ một ghim mà một đầu vào không còn khớp nữa, lần push dừng lại trước khi dựng bất kỳ kho lưu trữ nào hoặc liên hệ với bất kỳ registry nào. Thông báo từ chối nêu tên thực thể và mọi đầu vào như vậy — mỗi đầu vào là một remote source, một imported file hoặc một local source file — cùng với lệnh cần chạy: aggrega pin trên thực thể, --pin-sources trên lần push bạn vừa chạy, hoặc pin_sources_at_push cho mọi lần push trong workspace. Đây chính là lời từ chối mà một lần pull đưa ra với cùng tệp lock đó, An entity reads an input the lock beside it records no pin for (Một thực thể đọc một đầu vào mà tệp lock bên cạnh không ghi ghim nào cho nó), kèm các cách khắc phục riêng của push. Vì vậy, một Recipe hoặc FeatureRecipe mà lần push xuất bản sẽ mang, bên trong gói của nó, một tệp lock ghi lại mọi ghim mà bước ghim lẽ ra đã ghi vào thời điểm nó được xuất bản.
Hai loại thực thể không có gì để ghim và được xuất bản nguyên trạng: một thực thể không đọc nguồn từ xa nào, không nhập tệp nào và không nêu nguồn cục bộ nào, và một Recipe có tọa độ nguồn từ xa được điền từ một mẫu. Nguồn đó chỉ trỏ tới một artifact khi một Release điền mẫu vào, nên ghim của nó thuộc về lockfile của từng Release, và lần push không yêu cầu ghim đó nằm cạnh thực thể. Một Component, một Feature, một thư viện, một Aggregate hoặc một Plugin không đọc gì mà tệp lock ghi lại và không bao giờ bị từ chối ở đây.
So sánh ghim của một nguồn từ xa nghĩa là phải tải nguồn đó về, như aggrega pin làm, vì một ghim không còn khớp chỉ lộ ra khi đối chiếu với những gì nguồn đang cung cấp hiện tại. Do đó, một lần push trên thực thể có nguồn như vậy sẽ liên hệ với máy chủ của nguồn trước khi liên hệ với registry. Phép so sánh đọc một Recipe hoặc FeatureRecipe theo cách bước ghim đọc, thông qua catalog, nên một thực thể mà catalog từ chối đọc — chẳng hạn một tài liệu không đạt schema của loại nó — sẽ bị từ chối ở đây với chính lý do của catalog.
Khi không tìm thấy workspace nào và cũng không có workspace nào được chỉ định, một lần push cần tải một nguồn từ xa để so sánh sẽ bị từ chối trước khi tải, giống như aggrega pin. Phép so sánh tải từng nguồn từ xa mà thực thể viết đầy đủ vào bộ nhớ đệm artifact, đúng như bước ghim, và một bộ nhớ đệm được ghi trong một thư mục mà từ đó không tìm thấy workspace nào sẽ biến thư mục đó thành một workspace. Vì vậy, khi không có gì chỉ định một thư mục gốc và không có gì neo một thư mục gốc — từ thư mục bạn chạy push, hoặc, với một thực thể được chỉ định bằng đường dẫn tuyệt đối, từ chính thư mục của thực thể — một lần push một Recipe hoặc FeatureRecipe có nguồn như vậy sẽ dừng trước khi tải nguồn, kể cả dry run và --pin-sources, và nêu tên nguồn, thư mục cùng hai cách giải quyết: chỉ định workspace của bạn bằng --workspace-root hoặc AGGREGA_WORKSPACE_ROOT, hoặc thêm vào thư mục đó một tệp .aggrega-config.yaml có khối workspace:. Phép so sánh không tải gì cho hai loại thực thể ở trên, cũng như cho thực thể có nguồn cục bộ, nên mỗi thực thể đó được so sánh với tệp lock của nó và được xuất bản ở đó như ở bất kỳ nơi nào khác; còn mọi loại khác không bị ràng buộc với tệp lock và không bị từ chối vì lý do này. Cấu hình liệt kê các lệnh khác mà điều này áp dụng.
aggrega push --pin-sources chạy chính bước đó cho bạn, trước tiên. Bước này chạy trước khi dựng gói, nên tệp lock nó ghi nằm trong artifact được xuất bản và digest được xuất bản bao gồm cả tệp đó; và nó chạy trước mọi lời từ chối khác đánh giá thực thể, nên thứ được đánh giá là thực thể sau khi đã ghim. Chỉ có quy tắc thư mục ở trên được áp dụng trước, vì bước này ghi tệp lock duy nhất mà thư mục chứa. Nó ghi đúng các byte mà aggrega pin ghi, nên lời từ chối ở trên không bao giờ xảy ra trong lần chạy đó: tệp lock vừa được ghi ghi lại chính xác những gì lời từ chối sẽ đối chiếu. Khóa workspace pin_sources_at_push biến điều này thành mặc định cho mọi lần push, và --pin-sources=false bỏ qua bước này cho một lần chạy, khiến lời từ chối quay trở lại. Bước này ghi cạnh thực thể, nên cần một vị trí có thể ghi — và một lần push luôn có vị trí đó, vì nó xuất bản tài liệu bạn chỉ định.
--dry-run trả lời đúng như lần xuất bản sẽ trả lời. Khi không có --pin-sources, nó từ chối một thực thể chưa được ghim đúng như lần xuất bản, nên một dry run báo cáo được một gói nghĩa là lời từ chối này sẽ cho gói đó đi qua. Khi có --pin-sources, bước ghim chạy ở chế độ dry run: nó in ra tệp lock lẽ ra sẽ ghi và không ghi gì, và các thông tin về gói theo sau mô tả thư mục ở trạng thái hiện tại, không có tệp lock đó — nên digest là digest của một lần xuất bản không có tệp đó, và nếu tệp lock là mới thì kích thước và, với một thực thể không nêu gì khác, kiểu media cũng vậy. Lời từ chối không xảy ra, vì lần xuất bản lẽ ra đã ghim trước.
Thực hành tốt nhất: một thay đổi đối với phiên bản bạn đã xuất bản sẽ đi vào một phiên bản mới, rồi ghim. Sao chép thực thể sang một thư mục phiên bản mới, thực hiện thay đổi ở đó, ghim nó và xuất bản. Phần mà sản phẩm thực thi là mục tiếp theo: xuất bản nội dung khác tại một phiên bản đã được xuất bản sẽ bị từ chối. Phần còn lại — không ghim lại một phiên bản đã xuất bản sau khi chỉnh sửa nó trong workspace của bạn — là do bạn tự duy trì; không có gì từ chối việc đó ở máy cục bộ, vì ghim lại là hợp lệ đối với một thực thể bạn chưa xuất bản.
Registry, tag và định địa chỉ theo nội dung
Registry đích là --registry <ref> khi được cung cấp, nếu không thì là default_registry của workspace (mặc định là hub.aggrega.ai). Tag là metadata.version của thực thể, và đường dẫn repository được suy ra từ kind và tên của nó, nên nơi một phiên bản đã xuất bản được đặt không phụ thuộc vào thư mục mà nó được xuất bản từ đó.
Một default_registry có thể mang một đường dẫn repository, và một lần xuất bản qua nó sẽ được đặt dưới đường dẫn đó. Với default_registry: ghcr.io/acme, Component core/api-server ở phiên bản 1.0.0 được xuất bản tại ghcr.io/acme/component/core/api-server:1.0.0 — chính nơi mà một lần pull qua cùng giá trị mặc định đó tải nó về, nên chữ ký được đính kèm ở đây chính là chữ ký mà lần pull đó tìm thấy. --registry chỉ định một host, và một lần xuất bản do nó điều hướng sẽ được đặt tại host đó mà không có đường dẫn. Dù đích đến được chỉ định theo cách nào, yêu cầu ký và cấu hình ký được áp dụng là những gì được lưu cho host của nó: một đường dẫn không bao giờ chọn một chính sách khác. Cách viết một đường dẫn được trình bày trong cách viết một registry host.
Manifest ghi digest của các byte được xuất bản, còn lockfile ghi digest của những gì chúng chứa. OCI manifest mà một lần push ghi ra chỉ định digest của tài liệu hoặc archive được xuất bản, và aggrega pull từ chối một bản tải về không khớp với nó, nên các byte bị thay đổi giữa lúc xuất bản và lúc pull sẽ bị phát hiện. Lockfile mà một lần pull ghi ra ghi nhận thực thể bằng một digest khác: digest của nội dung của nó — đường dẫn và các byte của từng tệp, và không có gì về cách archive được nén hay các bit quyền của các tệp trong đó. Đó là digest mà một lần pull trong chính workspace của tác giả ghi nhận cho cùng thực thể đó trong thư mục catalog của nó, nên tác giả và mọi bên sử dụng một lần xuất bản đều ghi nhận cùng một giá trị, và một bản build ở bất kỳ phía nào cũng từ chối nội dung không còn khớp với nó. Hai digest trả lời các câu hỏi khác nhau: digest của manifest kiểm tra bản tải về, còn digest của lockfile là danh tính của thực thể.
Xuất bản đè lên một phiên bản đã có
Trước khi tải lên bất kỳ byte nào, aggrega push phân giải những gì registry đích đã lưu tại tham chiếu mà nó sắp ghi và so sánh với nội dung đang có. Có ba kết quả:
- Chưa có gì được xuất bản ở đó — lệnh push tiếp tục và xuất bản bình thường.
- Cùng nội dung — không có gì được tải lên, và lệnh báo rằng phiên bản đã được xuất bản, nên một lần push lặp lại hoặc thử lại không phải là lỗi. Những gì một lần push trước đó chưa đính kèm — chữ ký, hoặc ngày xuất bản — sẽ được đính kèm lúc này, như Hoàn tất một lần xuất bản mà lần push trước để dở mô tả.
- Nội dung khác — lệnh push dừng lại, nêu digest đã được xuất bản và digest mà nó lẽ ra đã ghi. Không có cờ nào buộc nó vượt qua.
Vì vậy, một phiên bản đã được xuất bản luôn tiếp tục chỉ đến các byte được xuất bản dưới nó. Nội dung đã thay đổi được xuất bản dưới một metadata.version mới; aggrega lint --pre-publish trả lời câu hỏi tiếp theo — phiên bản đó phải thay đổi bao xa — bằng cách phân loại thay đổi so với phiên bản đã xuất bản trước đó.
--dry-run in ra digest mà một lần push sẽ ghi, bên cạnh tham chiếu mà nó sẽ ghi vào:
aggrega push (dry-run): <reference>:<tag> (<digest>)Đó chính là digest mà lệnh push so sánh với những gì đã được xuất bản, được tính theo cùng cách chỉ từ nội dung, và việc in nó không liên hệ với registry nào. Vì thế, bạn có thể đối chiếu nội dung đang có với digest mà một phiên bản đã được xuất bản trước khi push bất cứ thứ gì: nếu chúng khác nhau tại một phiên bản đã xuất bản, lệnh push sẽ bị từ chối. Với --pin-sources, đó là digest của thư mục ở trạng thái hiện tại, như Ghim trước khi xuất bản mô tả.
Hoàn tất một lần xuất bản mà lần push trước để dở
Một lần push ghi nội dung trước rồi mới đính kèm chữ ký và ngày xuất bản, nên một lần push thất bại ở một trong các lần đính kèm đó — sau các lần thử lại của nó — sẽ để nội dung được xuất bản mà thiếu phần đó, và thoát với mã khác không, nêu ra thứ nó không thể đính kèm. Chạy lại cùng lệnh push sẽ hoàn tất lần xuất bản đó. Nó thấy nội dung đã được xuất bản, in dòng Already published:, không tải lên gì, và đính kèm những gì phiên bản còn thiếu, mỗi thứ trên dòng mà một lần xuất bản đầu tiên in cho nó:
- Chữ ký, khi lần push này có ký. Chữ ký được đính kèm khi phiên bản không mang chữ ký nào được tính là của lần xuất bản này. Khi cấu hình của bạn ghim một chính sách tin cậy cho host của đích — một
public_keyhoặctrusted_identities, hoặc vớihub.aggrega.ailà mức cơ sở tích hợp sẵn — một chữ ký được tính khi nó được xác minh theo chính sách đó, nên một chữ ký mà chính sách không chấp nhận không bao giờ được coi là của chính lần xuất bản. Khi chính sách không ghim cả hai, không chữ ký nào có thể được xác minh theo nó, nên mọi chữ ký mà phiên bản mang đều được tính và lệnh push chỉ ký một phiên bản không mang chữ ký nào; nếu đánh giá bằng xác minh ở đây thì mỗi lần chạy sẽ đính kèm thêm một chữ ký. - Ngày xuất bản, khi quy tắc về ngày yêu cầu một ngày — được đọc từ chữ ký vừa đính kèm, hoặc từ chữ ký đã được tính — và phiên bản hoàn toàn không mang referrer published-at nào. Một lần push không ký sẽ nợ một ngày như một lần xuất bản không ký, bất kể những chữ ký nào được đính kèm vào phiên bản sau đó. Ngày mà nó ghi là theo đồng hồ của chính lần push này: thời điểm lần xuất bản được hoàn tất, muộn hơn thời điểm nội dung lần đầu được ghi lên, vì không có gì registry cung cấp ghi lại thời điểm đó.
Một lần xuất bản đã hoàn tất sẽ không được đính kèm thêm gì, dù lệnh push được lặp lại bao nhiêu lần. Trước khi đính kèm bất cứ thứ gì, lệnh push đọc xem phiên bản mang những chữ ký và ngày nào và tạo mọi chữ ký mà nó còn nợ. Một câu hỏi nó không thể trả lời — một danh sách hoặc một chữ ký nó không đọc được, hoặc một chữ ký nó không thể đánh giá vì không lấy được gốc tin cậy — và một chữ ký nó không thể tạo, mỗi trường hợp đều thoát với mã khác không mà không đính kèm gì, thay vì được coi là phiên bản không mang gì.
Khi registry làm một lần ghi thất bại
Một lần push ghi vào registry theo từng bước: nội dung — đối với một Plugin, đó là thực thể và tệp .wasm của nó — rồi đến manifest đặt tên cho nội dung đó, rồi đến tag phiên bản, rồi đến chữ ký và ngày xuất bản bên cạnh nó. Mỗi bước ghi được thử lại khi nó thất bại theo cách mà một lần thử sau có thể thành công: registry trả về lỗi máy chủ (bất kỳ trạng thái 5xx nào, trừ 503 kèm Retry-After) hoặc 408 Request Timeout, hoặc kết nối bị hết thời gian chờ, bị đặt lại, hoặc kết thúc giữa chừng một phản hồi. Một bước được thử tối đa ba lần, chờ nửa giây trước lần thử thứ hai và một giây trước lần thử thứ ba.
Registry yêu cầu giảm tốc độ sẽ được chờ, và việc chờ không tiêu tốn lần thử nào trong số đó. Khi gặp 429 Too Many Requests, hoặc 503 kèm Retry-After, mọi yêu cầu tới registry đó — đọc cũng như ghi — chờ đúng khoảng thời gian registry yêu cầu rồi được gửi lại, và một bước có nội dung bị từ chối sẽ bắt đầu lại như một lần tải lên mới, không có số lần thử cố định, cho đến khi registry không trả lời gì ngoài “giảm tốc độ” trong năm phút. Registry yêu cầu giảm tốc độ mô tả việc chờ và sự từ chối chấm dứt việc chờ đó.
Mỗi lần thử là một lần tải lên mới với cùng các byte, không bao giờ là gửi lại yêu cầu đã thất bại. Một registry đã nhận phần thân của một lần tải lên có thể từ chối cùng yêu cầu đó lần thứ hai, và một lần tải lên mới mới là điều nó chấp nhận. Nội dung mà registry đã giữ được tính là đã tải lên, và một bước được thử lại sẽ ghi đúng những gì lần thử đầu tiên lẽ ra đã ghi, nên một lần thử đã thành công nhưng mất phản hồi không ghi gì hai lần: manifest giữ nguyên digest của nó, và phiên bản mang một chữ ký và một ngày xuất bản.
Mọi lỗi khác kết thúc bước đó ngay lập tức: thông tin xác thực bị từ chối (401, 403, hoặc không có thông tin xác thực nào được lưu cho registry), bất kỳ phản hồi nào khác mà registry trả về, một registry hoàn toàn không thể kết nối được, hoặc một lần push mà bạn ngắt. Một bước vẫn thất bại sau lần thử cuối cùng sẽ làm lệnh thất bại, và thông báo lỗi nêu tên bước đó — nội dung, manifest, tag, chữ ký hoặc ngày xuất bản. Những gì các bước trước đã xuất bản vẫn được giữ nguyên là đã xuất bản; Ký và Ngày xuất bản cho biết điều đó có ý nghĩa gì đối với phiên bản.
Với những lỗi đó, chỉ các thao tác ghi được thử lại. Việc đọc những gì registry đã giữ tại phiên bản, trước khi bất cứ thứ gì được tải lên, thì không được thử lại, dù nó vẫn chờ theo yêu cầu của một registry yêu cầu giảm tốc độ như mọi yêu cầu khác.
Ký
aggrega push có thể ký artifact ngay khi xuất bản và đính kèm chữ ký dưới dạng một OCI referrer — một bundle Sigstore (tương thích cosign) trên digest manifest bất biến của artifact. Chữ ký là một manifest anh em, nên việc ký không bao giờ đẩy lại hay thay đổi các byte đã xuất bản. Referrer đặt tên bundle của nó là signature.json, nên một client OCI thông thường khi kéo referrer theo digest của nó sẽ ghi bundle vào tệp đó.
Việc ký là ký trước khi đẩy: digest manifest đã được biết trước khi xuất bản, nên aggrega push tạo bộ ký và ký digest trước khi bất kỳ byte nào tới registry. Nếu không tạo được bộ ký hoặc việc ký thất bại, lần đẩy bị từ chối trước khi bất cứ thứ gì được tải lên — không có gì được xuất bản, nên một lần ký thất bại không bao giờ để lại nội dung chưa ký trên registry. Trước khi từ chối, một lời gọi ký thất bại tạm thời — bất kỳ thất bại nào mà một lần ghi registry được thử lại, hoặc cơ quan cấp chứng chỉ keyless báo rằng nó không thể xử lý identity token — được thử lại, tối đa ba lần với cùng khoảng chờ. Bên trong một lời gọi 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ủ trước hết sẽ được gửi lại tới dịch vụ đó, như aggrega sign mô tả.
Chữ ký được đính kèm sau khi nội dung đã tới nơi, nên một lần đính kèm thất bại sẽ để nội dung được xuất bản mà không có chữ ký. Việc đính kèm là một lần ghi, được thử lại như Khi registry làm một lần ghi thất bại mô tả. Nếu vẫn thất bại, lệnh thoát với mã khác không và nêu tên chữ ký không đính kèm được, và một bên tiêu thụ có registry yêu cầu chữ ký sẽ từ chối phiên bản cho tới khi một chữ ký được đính kèm. Chạy lại cùng lần đẩy đó sẽ đính kèm nó, như Hoàn tất một lần xuất bản mà lần đẩy trước để dở mô tả; aggrega sign đính kèm một chữ ký vào phiên bản đã xuất bản theo tham chiếu.
Một lần xuất bản yêu cầu chữ ký khi khối signing riêng của registry đích đặt required: true, hoặc khi khối signing cấp cao nhất đặt điều đó cho mọi registry — mỗi khối chỉ giới hạn ở các loại mà kinds của nó liệt kê, nếu có liệt kê. Một lần xuất bản như vậy ký theo mặc định, và --sign yêu cầu ký một cách tường minh. Không có flag nào để đẩy nội dung chưa ký khi chữ ký là bắt buộc — lần đẩy đó luôn dừng lại.
Hai chế độ ký:
- Keyless (mặc định) — một khóa tạm thời gắn với một danh tính OIDC bằng một chứng chỉ Fulcio ngắn hạn, được ghi vào nhật ký minh bạch Rekor. Fulcio và Rekor mặc định dùng các instance Sigstore công cộng (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). Dấu thời gian tin cậy của keyless đến từ việc được đưa vào nhật ký minh bạch của Rekor; một cơ quan cấp dấu thời gian RFC3161 riêng là tùy chọn — cung cấp--timestamp-urlvới một endpoint đầy đủ để bật nó. Tại một terminal tương tác, ký keyless không cần flag nào: CLI mở trình duyệt để lấy một OIDC identity token ngắn hạn. Trên GitHub Actions cũng không cần flag nào: CLI tự động tạo OIDC token của workflow từ endpoint môi trường của runner. Với các trường hợp không tương tác / CI khác, hãy exportAGGREGA_IDENTITY_TOKEN(hoặcSIGSTORE_ID_TOKEN), hoặc truyền--identity-token; khi không có token được cung cấp, không có endpoint môi trường và không có terminal, lần đẩy bị từ chối. Xem environment-variables.md để biết mô hình token cho CI. - Keyed (
--key) — một khóa ECDSA P-256 được giữ ngoại tuyến (PEM tương thích cosign), lối thoát cho các môi trường không có nhà cung cấp danh tính OIDC. Không kết nối tới nhà cung cấp danh tính, cơ quan cấp chứng chỉ hay nhật ký minh bạch nào.
Các URL dịch vụ keyless và đường dẫn khóa keyed cũng có thể được đặt trong .aggrega-config.yaml dưới một khối signing: (toàn cục và riêng từng registry); một flag ghi đè cấu hình, và cấu hình ghi đè mặc định công cộng. OIDC identity token không bao giờ là một trường cấu hình (nó là một bí mật ngắn hạn), và khóa riêng không bao giờ được viết trực tiếp trong cấu hình — chỉ có đường dẫn tới nó.
Ngày xuất bản
Thời điểm tạo của manifest được cố định, nên digest của manifest chỉ phụ thuộc vào nội dung được xuất bản và không bao giờ phụ thuộc vào thời điểm xuất bản. Thay vào đó, ngày một phiên bản được xuất bản đi kèm bên cạnh nó, và nguồn của ngày đó phụ thuộc vào chữ ký:
- Chữ ký keyless đã mang sẵn ngày đó. Mục nhật ký minh bạch của nó ghi lại thời điểm nhật ký tích hợp chữ ký, và lời cam kết có chữ ký của nhật ký chứng thực thời điểm đó.
aggrega pushkhông ghi thêm gì. - Chữ ký keyed, hoặc không có chữ ký, không mang thời gian nào. Vì vậy, sau khi thực thể và chữ ký (nếu có) đã được đưa lên,
aggrega pushgắn một referrer published-at nhỏ vào manifest — được đặt tênpublished-at.jsoncho client OCI thông thường — chứa một dấu thời gian RFC 3339 theo UTC, chính xác đến giây, được đọc từ đồng hồ của chính máy xuất bản. Nó không được ký: đó là tuyên bố của người xuất bản, và người đọc ghi nhận nó như vậy. DòngPublication date attached:báo cáo giá trị này.
Giống như chữ ký, referrer published-at là một manifest anh em trỏ ngược về manifest đã xuất bản, nên nó không làm thay đổi digest nào và không thay đổi tag nào, và việc kiểm tra khi xuất bản đè lên một phiên bản hiện có không bị ảnh hưởng bởi nó. Một lần push lặp lại cùng nội dung chỉ gắn ngày cho phiên bản chưa có ngày, ghi theo đồng hồ của chính nó — xem Hoàn tất một lần xuất bản mà lần push trước để dở dang. Ngày được đọc từ đồng hồ một lần, trước khi thử gắn lần đầu, nên một lần gắn được thử lại — xem Khi registry làm hỏng một thao tác ghi — ghi cùng một ngày. Một lần push đã xuất bản nội dung nhưng không thể gắn ngày sau các lần thử đó sẽ thoát với mã khác 0 và nêu rõ những gì chưa được gắn. aggrega registry update ghi lại ngày của mỗi phiên bản cùng với nguồn nào trong hai nguồn đã cung cấp ngày đó.
Ngoại tuyến
Việc phát hành là một lượt khứ hồi qua mạng và không có dạng nào không phải như vậy, nên ở chế độ ngoại tuyến — khóa offline ở cấp cao nhất trong tệp cấu hình, AGGREGA_OFFLINE, hoặc --offline — aggrega push từ chối trước khi đọc thực thể của bạn. Lời từ chối nêu rõ cái nào trong ba cái đó đã bật chế độ này, đó là điều người đọc cần khi chính cấu hình đã commit của dự án bật nó lên chứ không phải bất cứ thứ gì họ đã gõ.
--dry-run là ngoại lệ, và nó là ngoại lệ vì những gì nó làm: nó tính toán gói, in ra tham chiếu mà nó sẽ phát hành và digest mà lần phát hành đó sẽ tạo ra, và không bao giờ liên hệ với registry. Điều đó khiến nó trở thành dạng phát hành an toàn khi ngoại tuyến chứ không xung đột với chế độ này, và nó vẫn hoạt động trong chế độ đó — với một lưu ý. Một Recipe hoặc FeatureRecipe có source: từ xa được viết đầy đủ sẽ được tải nguồn đó về để so sánh pin của nó, và ở chế độ ngoại tuyến việc tải đó bị từ chối bằng thông báo riêng, nên một lần chạy thử trên thực thể như vậy dừng lại ở đó thay vì báo cáo một gói mà nó không thể đảm bảo.
Để phát hành trong một lần chạy từ một workspace có cấu hình ngoại tuyến, hãy truyền --offline=false.
Biến môi trường
Các đầu vào ký và registry đích có thể được cung cấp qua môi trường, ghi đè .aggrega-config.yaml, trong khi flag vẫn được ưu tiên hơn:
AGGREGA_IDENTITY_TOKEN— token định danh OIDC không dùng khóa (biến môi trường tương ứng với--identity-token).SIGSTORE_ID_TOKENđược chấp nhận như một bí danh tương thích với hệ sinh thái sigstore, xếp hạng thấp hơnAGGREGA_IDENTITY_TOKENvà endpoint GitHub Actions có sẵn trong môi trường. Token không bao giờ là một trường cấu hình.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— các URL dịch vụ ký không dùng khóa.AGGREGA_SIGNING_KEY_PATH— một đường dẫn trỏ tới tệp PEM của khóa dùng cho chế độ ký có khóa (không bao giờ là bản thân dữ liệu khóa).AGGREGA_DEFAULT_REGISTRY— registry đích khi bỏ qua--registry.
Thứ tự ưu tiên là flag > môi trường > cấu hình > mặc định. Xem environment-variables.md để biết danh sách đầy đủ và mô hình thứ tự ưu tiên.
Xác thực
aggrega push đọc thông tin xác thực registry giống như aggrega pull — từ cấu hình thông tin xác thực Docker và các credential helper mà nó chỉ định. Chạy aggrega login <registry>, lệnh không cần công cụ nào khác, hoặc docker login <registry> trước khi push lên một registry riêng tư. Xem aggrega-pull.md để biết cấu hình đó được đọc từ đâu.
Xem thêm
- ./aggrega-sign.md — ký một artifact đã được xuất bản sau khi xuất bản (phần tương ứng sau xuất bản của
--sign). - ./aggrega-lint.md — cổng kiểm tra trước khi xuất bản (
--pre-publish) nên chạy trước một lần push. - ./aggrega-pull.md — phía tiêu thụ, nơi phân giải và ghim những gì
pushxuất bản. - ./aggrega-serve.md — daemon cung cấp chính thao tác xuất bản này tại
aggrega/publishEntity, để trình soạn thảo có thể chạy nó mà không rời phiên làm việc; nó chỉ chạy khi một yêu cầu chỉ định nó, và trả về tham chiếu, digest đã xuất bản — khi chạy thử, là digest mà--dry-runin ra — lời gọi đã đi được bao xa, và các mục mà lệnh này cảnh báo dưới dạngwindowsUnusableEntries. - ./aggrega-mcp.md — cùng khả năng này dưới dạng công cụ
publish-entity, mà một trợ lý có thể gọi, trả về các mục đó dưới dạngwindows_unusable_entries. Hãy đọc những gì trang đó nói về việc cho phép nó trước khi bạn cho phép. - ../../architecture/13-catalog-and-registry.md — mô hình catalog, registry và mediatype OCI.
Cú pháp
aggrega push <entity-path> [flags]Mô tả
Publish a single catalog entity to an OCI registry, where other workspacesresolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to<registry>/<kind>/<metadata.name>:<metadata.version>, the repository pathlowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Pluginits metadata.pluginType, as a segment between <kind> and <metadata.name>. Thetag is the entity's own metadata.version. Run "aggrega push --list-kinds" forthe kinds this binary publishes, one per line and nothing else, so a script canread it directly. Release and Manifest are deployment-side inputs rather thancatalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: anentity of any other kind is refused when another entity sits in its directory,before anything is pinned or bundled, and the refusal names the entity in the way.The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads itbefore it is bundled, and one that read refuses is refused here for the samereason: a document that fails its kind's schema, a path naming content outsidethe entity's own directory, which would not travel with the entity, or a schemaa Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so ametadata.version that is not a semantic version is refused. Its .wasm must thenagree with the entity on what the plugin offers and on its version, and a .wasmwhose version says it was built from a working tree with uncommitted changes —the -dirty mark a build adds — is refused. A version disagreement and a buildfrom uncommitted changes are both cleared by building the plugin from a cleancheckout of the commit its release tag names, never by copying the version itreports into the entity. A development version such as 1.0.0-3-g1a2b3c4, builtfrom a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself namesbeside it — a Recipe's or FeatureRecipe's local source, each file an $import:names, the entity.lock beside it, and each schema file a Component or Featureimports — and nothing else in its directory. An entity that names nothingpublishes as its document, unchanged; one that names a file publishes as agzipped archive of the document and those files. A directory it names travelswith every file under it that the ignore rules recorded in its entity.lock keep:the rules the plugin serving its capability declared, and the author's own.aggregaignore beside it, composed when the entity was pinned. A symbolic linkamong those files is refused rather than followed. A local source written as atemplate names no one directory until a Release fills it in, so an entity withone carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windowscannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or apart ending in a full stop or a space. On Windows, aggrega refuses to unpacksuch a file, so a Windows workspace cannot use the version. The warning iswritten to standard error on every platform, one line per file, the entitydocument's own file name judged with the rest, and it refuses nothing: the push,or its dry run, goes ahead or stops exactly as it would without it. An entitythat names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the executebit included — in the checkout it is published from. The OCI manifest names thedigest of the published bytes, so "aggrega pull" refuses a download that doesnot match it. The lockfile a pull writes records the entity by the digest of itscontent — each file's path and its bytes — which is the digest a pull in theauthor's own workspace records for the same entity in its catalog directory, soa build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is madeover the manifest digest before any bytes reach the registry, so a failedsigning refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what ispublished and never on when. Push states when it published beside the manifestinstead, as a small published-at attachment carrying this machine's clock, inUTC to the second — unless the signature it attached already carries a time atransparency log attests, as a keyless signature does. So a keyed or unsignedpublication writes one, and a keyless one does not. The attachment moves nodigest and changes no tag. "aggrega registry update" records the date, withwhich of the two it came from.
Push refuses to replace content already published at the same version:publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lockbeside it, and pinning them is a step you run before publishing: aggrega pin.A push that does not run that step refuses an entity whose entity.lock ismissing a pin, or holds one an input no longer matches, and names the step.Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, tohave push run that same step first, so the lock it writes is part of what ispublished; --pin-sources=false skips it for one run.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--dry-run | false | Tính toán bundle và in ra |
--entity | — | Đường dẫn tới tệp YAML của thực thể cần xuất bản (hoặc truyền dưới dạng đối số vị trí) |
--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. |
--list-kinds | false | Liệt kê mọi loại thực thể có thể xuất bản, rồi thoát mà không xuất bản gì. Đầu ra máy có thể đọc được và có định dạng ổn định: mỗi dòng một loại, theo thứ tự đã sắp xếp, không có gì khác. |
--pin-sources | false | Chạy bước ghim của tác giả thực thể trên thực thể trước khi đóng bundle, để tệp entity.lock mà bước này ghi bên cạnh nó trở thành một phần của nội dung được xuất bản, thay vì từ chối một thực thể có tệp lock không ghi lại các ghim của nó. Đây là cùng bước với aggrega pin, ghi ra cùng các byte. Bước này ghi bên cạnh thực thể, nên chỉ chạy khi thực thể có vị trí ghi được: một tài liệu trong thư mục mà nó được đọc từ đó — điều mà một lần push luôn có, vì nó xuất bản tài liệu thực thể mà bạn chỉ định. Ghi đè pin_sources_at_push của workspace theo cả hai chiều: —pin-sources ghim cho lần chạy này và —pin-sources=false thì không, bất kể thiết lập là gì |
--plugin | — | Đường dẫn tới artifact .wasm cục bộ cho một thực thể Plugin. Bắt buộc khi xuất bản một Plugin: publish đẩy artifact .wasm lên, tính digest nội dung của nó, rồi đẩy thực thể lên. |
--registry | — | Máy chủ registry đích (ghi đè default_registry của workspace) |
--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. |
--sign | false | Ký artifact đã xuất bản và đính kèm chữ ký dưới dạng OCI referrer. Khi bỏ qua, việc ký tuân theo chính sách của registry đích. |
--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. |