aggrega sign
aggrega sign menandatangani satu atau lebih artefak katalog yang sudah dipublikasikan dan melampirkan setiap tanda tangan sebagai referrer OCI. Perintah ini adalah padanan pascapublikasi dari aggrega push --sign: gunakan untuk menandatangani artefak yang dipublikasikan tanpa tanda tangan, atau untuk menandatangani seluruh batch artefak dalam satu pemanggilan. Perintah ini tidak menambahkan tanda tangan kedua pada artefak yang sudah membawa tanda tangan yang diverifikasi oleh kebijakan kepercayaan registrinya.
Apa yang dilakukannya
aggrega sign menentukan digest yang sudah disimpan registry untuk setiap <reference>, menandatangani digest tersebut, dan melampirkan bundel tanda tangan sebagai referrer. Perintah ini tidak pernah melakukan push ulang, tag ulang, atau dengan cara lain mengubah byte yang telah dipublikasikan — artefak bersifat immutable, dan tanda tangan adalah manifest saudara yang menunjuk kembali ke artefak tersebut. Jadi, sebuah artefak dapat ditandatangani setelahnya tanpa kenaikan versi.
Sebelum menandatangani, perintah ini membaca tanda tangan yang sudah dimiliki referensi dan menilainya terhadap kebijakan kepercayaan yang disimpan workspace ini untuk registry referensi tersebut — kebijakan yang digunakan aggrega pull untuk verifikasi. Jika ada satu tanda tangan yang terverifikasi, siapa pun penandatangannya, referensi tersebut sudah ditandatangani: perintah mencetak Already signed: beserta referensi, digest-nya, identitas penandatangan dan, jika log transparansi mencatat tanda tangan tersebut, waktunya — tanda tangan semacam itu yang paling awal jika ada beberapa — tidak melampirkan apa pun, dan menghitung referensi tersebut sebagai sudah ditandatangani. Pembaca yang memverifikasi tanda tangan keyless menentukan tanggal sebuah versi berdasarkan tanda tangan paling awal yang terverifikasi dan menyebut penandatangan tanda tangan tersebut, seperti dijelaskan aggrega registry update, sehingga tanda tangan tambahan hanya akan menambahkan sebuah referrer dan sebuah entri log transparansi tanpa mengubah apa pun yang diambil pembaca semacam itu dari versi tersebut.
Registry yang kebijakannya tidak menetapkan kunci publik maupun identitas tepercaya tidak memberikan dasar apa pun untuk menilai tanda tangan, sehingga referensi di registry tersebut tetap ditandatangani apa pun tanda tangan yang sudah dimilikinya. Referensi yang hanya memiliki tanda tangan yang tidak diterima kebijakan tetap ditandatangani, karena tidak satu pun dari tanda tangan tersebut berlaku bagi pembaca yang memverifikasi berdasarkan kebijakan itu.
Tanda tangan berupa bundel Sigstore (kompatibel dengan cosign), format yang sama yang dilampirkan aggrega push --sign dan diverifikasi aggrega pull. Referrer menamai bundel tersebut signature.json, sehingga klien OCI generik yang menarik referrer berdasarkan digest-nya akan menulis bundel ke file tersebut.
Penandatanganan batch
Berikan beberapa referensi untuk menandatanganinya dalam satu pemanggilan:
aggrega sign \ hub.example.com/component/core/api-server:1.0.0 \ hub.example.com/component/core/worker:1.0.0 \ hub.example.com/feature/core/telemetry:2.1.0Penandatanganan tanpa kunci me-resolve identitas satu kali untuk seluruh batch — satu autentikasi interaktif, atau di GitHub Actions endpoint OIDC bawaan runner — dan menggunakannya kembali untuk setiap artefak, dengan menerbitkan sertifikat Fulcio berumur pendek yang baru per artefak. Token yang diperoleh secara interaktif atau yang diberikan digunakan kembali untuk setiap tanda tangan; endpoint bawaan mencetak token baru per tanda tangan. Referensi dapat menargetkan registri yang berbeda: masing-masing ditandatangani dengan satu identitas tersebut terhadap endpoint Fulcio dan Rekor yang dikonfigurasi untuk registrinya sendiri. Jalur berkunci (--key) menandatangani batch tanpa autentikasi sama sekali.
Penandatanganan bersifat lanjutkan-dan-laporkan: setiap referensi yang dapat ditandatangani akan ditandatangani, referensi yang gagal di-resolve, ditandatangani, atau dilampirkan akan dicatat, dan batch berlanjut ke referensi berikutnya alih-alih berhenti pada kegagalan pertama. Referensi yang sudah membawa tanda tangan yang lolos verifikasi dilaporkan sebagai sudah ditandatangani dan dihitung sebagai ditandatangani. Referensi yang tanda tangan yang sudah ada tidak dapat dibaca — registri tidak menyelesaikan daftarnya, atau sebuah tanda tangan tidak dapat diambil atau dinilai sementara tidak ada yang lolos verifikasi — dicatat sebagai gagal dan tidak ditandatangani: pertanyaan yang tidak terjawab tidak pernah dianggap sebagai artefak yang belum ditandatangani. Setelah batch selesai, jika ada referensi yang gagal, ringkasan yang mencantumkan referensi yang gagal dicetak ke stderr dan perintah keluar dengan kode bukan nol. Referensi yang berhasil tetap ditandatangani terlepas dari kegagalan referensi lain.
Menandatangani beberapa referensi sekaligus
Secara default, batch menandatangani referensi satu per satu. --jobs N menandatangani hingga N referensi sekaligus, dan tidak pernah lebih dari N. Setiap referensi tetap ditandatangani persis seperti jika ditandatangani sendirian: digest yang dipublikasikannya di-resolve, referensi dibiarkan apa adanya jika sudah membawa tanda tangan yang lolos verifikasi, dan jika tidak, referensi mendapat tanda tangannya sendiri — dalam mode keyless, dengan kunci efemeralnya sendiri, sertifikat berumur pendeknya sendiri, dan entri log transparansinya sendiri. Identitas tetap di-resolve sekali, untuk seluruh batch, sebelum referensi apa pun dibaca. Nilai di bawah 1 ditolak, dan tidak ada yang ditandatangani.
Dalam urutan apa pun referensi selesai, keluaran mempertahankan urutan referensi diberikan: baris-baris setiap referensi dicetak utuh begitu setiap referensi yang disebut sebelumnya selesai, sehingga baris dua referensi tidak pernah bercampur, dan ringkasan referensi yang gagal juga mencantumkannya dalam urutan itu. Satu konsekuensi dari menandatangani setiap referensi seolah-olah sendirian: batch yang menyebut artefak yang sama dua kali mendapat dua tanda tangan ketika keduanya ditandatangani sekaligus, karena tidak ada yang melihat tanda tangan yang lain selagi tanda tangan itu dibuat, sedangkan jika satu per satu, yang kedua menemukan tanda tangan yang pertama dan, jika kebijakan kepercayaan registrinya memverifikasinya, tidak melampirkan apa pun.
Default-nya 1 karena penandatanganan keyless menjangkau otoritas sertifikat dan log transparansi publik kecuali konfigurasi Anda menyebut yang lain, dan layanan-layanan tersebut membatasi jumlah permintaan yang mereka terima.
Satu kredensial per batch
Setiap referensi dalam satu pemanggilan ditandatangani dengan kredensial yang sama: satu kunci yang dipegang, atau satu identitas tanpa kunci. Kredensial mana yang dibutuhkan sebuah referensi ditentukan oleh konfigurasi untuk registrinya — signing.key_path yang berlaku untuk registri tersebut memilih kunci yang disebutkannya, dan jika tidak ada yang berlaku, referensi ditandatangani tanpa kunci. Jika referensi-referensi tersebut membutuhkan kredensial yang berbeda — konfigurasi menyebutkan kunci untuk satu registri dan tidak untuk registri lain, atau dua kunci yang berbeda — perintah tidak menandatangani apa pun dan menyebutkan registri di masing-masing sisi. Hal ini dilakukan sebelum identitas apa pun diminta dan sebelum registri apa pun dibaca, sehingga tidak ada yang dilampirkan dan tidak ada yang dimintai autentikasi untuk proses yang tidak akan dilanjutkan.
Sebagai gantinya, jalankan satu pemanggilan per kredensial: satu yang menyebutkan referensi pada registri yang ditandatangani dengan kunci, dan satu lagi yang menyebutkan sisanya. Kunci yang diberikan dengan --key berlaku untuk setiap referensi yang disebutkan, apa pun isi konfigurasi untuk setiap registri, sehingga pemanggilan dengan --key tidak pernah ditolak karena hal ini.
Batch ditolak alih-alih ditandatangani dengan kredensial mana pun yang dibutuhkan salah satu referensinya, karena tanda tangan tidak dapat ditarik kembali dari siapa pun yang telah mengambilnya. Berbeda dengan kegagalan per referensi yang dijelaskan di atas, ini adalah penolakan batch, bukan penolakan satu referensi: tidak ada referensi yang ditandatangani. Jika sebuah registri dalam batch mewajibkan tanda tangan, pesan menyebutkannya, sehingga penolakan terbaca sebagai penolakan atas penggabungan referensi, bukan sebagai pernyataan bahwa referensi tersebut tidak dapat ditandatangani. Pesan tersebut, beserta apa yang disebutkan setiap bagiannya, terdapat di References signed together need different signing credentials (Referensi yang ditandatangani bersama membutuhkan kredensial penandatanganan yang berbeda).
Kedaluwarsanya token identitas di tengah batch
Batch yang panjang dapat berlangsung lebih lama daripada token identitas berumur pendek. Di GitHub Actions hal ini bukan masalah: endpoint bawaan mencetak token baru untuk setiap tanda tangan, sehingga batch tidak pernah melampaui masa berlaku identitasnya. Untuk token yang diperoleh secara interaktif atau diberikan operator (--identity-token, AGGREGA_IDENTITY_TOKEN, atau SIGSTORE_ID_TOKEN), satu token melayani seluruh batch; jika token kedaluwarsa di tengah batch, referensi yang terdampak dicatat sesuai lanjutkan-dan-laporkan dan batch berlanjut. Jalankan ulang perintah untuk menandatangani referensi yang dilaporkan — atau, untuk batch skrip yang panjang, peroleh token baru di awal.
Untuk batch skrip, peroleh token satu kali di awal lalu ekspor token tersebut, sehingga setiap referensi ditandatangani tanpa bolak-balik ke browser:
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)aggrega sign hub.example.com/component/core/api-server:1.0.0aggrega sign hub.example.com/component/core/worker:1.0.0Lihat ./aggrega-auth.md untuk aggrega auth token.
Ketika suatu langkah gagal sementara
Setiap referensi ditandatangani dalam tiga langkah: digest yang dipublikasikan di-resolve, digest tersebut ditandatangani, lalu tanda tangannya dilampirkan. Dua di antaranya dicoba ulang ketika gagal dengan cara yang memungkinkan upaya berikutnya berhasil:
- Panggilan penandatanganan — pada setiap kegagalan yang membuat penulisan ke registry dicoba ulang, dan ketika otoritas sertifikat keyless melaporkan bahwa ia tidak dapat memproses token identitas.
- Pelampiran, yang menulis bundel tanda tangan dan manifest referrer ke registry — pada galat server, batas waktu habis, atau koneksi yang di-reset;
aggrega pushmencantumkan kegagalan-kegagalan tersebut. Setiap upaya merupakan unggahan baru atas byte yang sama, bukan pengiriman ulang permintaan yang gagal, dan pelampiran yang diulang menghasilkan satu tanda tangan, bukan dua.
Masing-masing dicoba paling banyak tiga kali, dengan jeda setengah detik lalu satu detik. Me-resolve digest adalah operasi baca dan tidak dicoba ulang. Registry yang meminta untuk memperlambat adalah kasus yang berbeda: setiap permintaan kepadanya, termasuk resolusi digest dan pelampiran tanda tangan, menunggu selama yang dimintanya, seperti dijelaskan dalam Registry yang meminta untuk memperlambat.
Panggilan penandatanganan keyless meminta hingga tiga layanan — otoritas sertifikat untuk sertifikat, log transparansi untuk entri, dan, jika dikonfigurasi, otoritas stempel waktu untuk stempel waktu — dan setiap permintaan dicoba ulang sendiri-sendiri di dalam panggilan. Permintaan yang dijawab salah satunya dengan 429 Too Many Requests atau galat server (untuk log transparansi, galat apa pun kecuali 501 Not Implemented) dikirim ulang ke layanan itu, sehingga dicoba paling banyak tiga kali, dengan jeda satu detik lalu dua detik; hanya permintaan itu yang diulang, sehingga entri log transparansi yang diminta lagi tidak meminta sertifikat kedua. Log transparansi juga diminta lagi ketika koneksi ke sana gagal, dan Retry-After yang dikirimnya bersama 429 atau 503 ditunggu selama yang dimintanya. Jawaban pembatasan laju atau galat server yang masih kembali setelah upaya-upaya tersebut menggagalkan panggilan penandatanganan, yang kemudian tidak dicoba ulang secara keseluruhan.
Langkah yang masih gagal setelah upaya terakhirnya dicatat untuk referensi tersebut berdasarkan continue-and-report, beserta galatnya, dan batch berlanjut — pelampiran yang gagal dilaporkan sebagai tanda tangan yang tidak dapat dilampirkan; kegagalan lainnya langsung dicatat.
Mode penandatanganan
- Keyless (default) — kunci sementara yang terikat ke identitas OIDC oleh sertifikat Fulcio berumur pendek, dicatat dalam log transparansi Rekor. Fulcio dan Rekor secara default menggunakan instans Sigstore publik (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). Stempel waktu tepercaya keyless berasal dari penyertaan dalam log transparansi Rekor; otoritas stempel waktu RFC3161 terpisah bersifat opsional — berikan--timestamp-urldengan endpoint lengkap untuk mengaktifkannya. Pada terminal interaktif, penandatanganan keyless tidak memerlukan flag: CLI membuka browser untuk memperoleh token identitas OIDC berumur pendek. Pada GitHub Actions juga tidak memerlukan flag: CLI membuat token OIDC workflow secara otomatis dari endpoint lingkungan runner. Untuk penggunaan non-interaktif / CI lainnya, eksporAGGREGA_IDENTITY_TOKEN(atauSIGSTORE_ID_TOKEN), atau berikan--identity-token; tanpa token yang diberikan, tanpa endpoint lingkungan, dan tanpa terminal, perintah ditolak. - Keyed (
--key) — kunci ECDSA P-256 yang disimpan offline (PEM yang kompatibel dengan cosign). Tidak ada penyedia identitas, otoritas sertifikat, atau log transparansi yang dihubungi; registry tetap dihubungi, untuk me-resolve setiap digest dan melampirkan tanda tangannya.
URL keyless dan path kunci keyed juga dapat berasal dari blok signing: di .aggrega-config.yaml (global dan per registry); flag menimpa konfigurasi, dan konfigurasi menimpa default publik. Dalam file tersebut, setiap URL ditulis sebagai URL https absolut — https://, sebuah host, serta secara opsional port dan path, seperti https://fulcio.sigstore.dev — dan nilai dalam bentuk lain, yaitu yang tanpa skema atau yang diawali http://, ditolak saat file dimuat, dengan menyebutkan file dan kuncinya. Token identitas OIDC tidak pernah menjadi kolom konfigurasi, dan kunci privat tidak pernah ditulis langsung — hanya path ke kunci tersebut.
Konstruksi serta perilaku tanda tangan dan lampirkan digunakan bersama dengan aggrega push, sehingga kedua perintah menandatangani dengan cara yang identik.
Variabel lingkungan
Masukan penandatanganan dapat diberikan melalui lingkungan, yang menimpa blok signing: pada .aggrega-config.yaml, sementara flag tetap diutamakan:
AGGREGA_IDENTITY_TOKEN— token identitas OIDC keyless (padanan lingkungan untuk--identity-token).SIGSTORE_ID_TOKENditerima sebagai alias interoperabilitas ekosistem sigstore, dengan prioritas di bawahAGGREGA_IDENTITY_TOKENdan endpoint lingkungan GitHub Actions. Token tidak pernah menjadi kolom konfigurasi.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— URL layanan keyless.AGGREGA_SIGNING_KEY_PATH— penunjuk path ke PEM kunci keyed (tidak pernah materi kunci).
aggrega sign menentukan konfigurasi penandatanganan dan variabel-variabel ini untuk host registry artefak, dengan cara yang sama seperti aggrega push. Urutan prioritasnya adalah flag > lingkungan > konfigurasi > default. Lihat environment-variables.md untuk daftar lengkapnya.
URL yang diberikan melalui salah satu variabel ini, atau melalui --fulcio-url, --rekor-url, atau --timestamp-url, diterima apa adanya. File konfigurasi diperiksa sebelum salah satunya diterapkan di atasnya, sehingga bentuk https yang diwajibkan untuk nilai-nilai file tersebut tidak berlaku bagi keduanya, dan URL yang salah bentuk baru gagal ketika penandatanganan menghubungi layanan tersebut.
Lihat juga
- ./aggrega-auth.md — memperoleh token identitas OIDC satu kali untuk sekumpulan penandatanganan keyless.
- ./aggrega-push.md — memublikasikan, dengan opsi menandatangani saat push (sign-before-push).
- ./aggrega-pull.md — sisi konsumen, yang memverifikasi tanda tangan terhadap kebijakan kepercayaan per registry.
- ./aggrega-serve.md — daemon menjalankan batch yang sama di
aggrega/signArtifacts, menentukan identitasnya dari permintaan atau lingkungan dan menolak alih-alih meminta masukan; permintaan di sana tidak menyebutkan kunci, sehingga penandatanganan keyed membaca bloksigning:milik workspace itu sendiri. - ./aggrega-mcp.md — kemampuan yang sama sebagai tool
sign-artifacts, yang dapat dipanggil oleh asisten, dan yang menerimakey_path. Baca apa yang dikatakan halaman tersebut tentang mengizinkannya sebelum Anda melakukannya.
Sinopsis
aggrega sign <reference>... [flags]Deskripsi
Sign amends already-published artifacts by attaching a signature to each as an OCI referrer. It does not re-push, re-tag, or otherwise mutate the published bytes — the artifacts are immutable; each signature is a sibling manifest pointing back at its artifact. With --key signatures are 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. Multiple references are signed in one invocation: the keyless identity is acquired once and reused across every artifact, and a fresh short-lived certificate is issued per artifact. Every reference in one invocation is signed with one credential: where the configuration names a held key (signing.key_path) for one reference's registry and none for another's, or two different keys, nothing is signed and the command says to run one invocation per credential; --key applies its key to every reference. A reference that already carries a signature its registry's trust policy verifies is reported as already signed, naming who signed it and when, and nothing is attached to it; a registry whose policy pins no public key or trusted identity gives nothing to judge a signature against, so a reference there is signed. Every other signable reference is signed; failures are collected and reported at the end, and the command exits non-zero if any reference failed — including one whose existing signatures could not be read, which is not signed. With --jobs N up to N references are signed at once; each is still signed exactly as it would be alone — when keyless, with its own certificate and its own transparency-log entry — and the output lists the references in the order they were given. The default, 1, signs one reference after another, because keyless signing reaches the public certificate authority and transparency log by default, and those limit how many requests they accept.Flag
| Flag | Default | Deskripsi |
|---|---|---|
--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. |
--jobs | 1 | Jumlah referensi yang ditandatangani sekaligus. Setiap referensi tetap ditandatangani persis seperti jika ditandatangani sendirian, dan keluaran mempertahankan urutan referensi diberikan. Minimal 1. |
--key | — | Path ke PEM kunci privat ECDSA P-256 yang Anda miliki untuk penandatanganan berkunci secara offline. Jika dihilangkan, penandatanganan tanpa kunci digunakan. |
--rekor-url | — | URL log transparansi Rekor untuk penandatanganan tanpa kunci. Jika dihilangkan, instans Rekor publik digunakan. |
--timestamp-url | — | URL otoritas stempel waktu RFC3161 opsional untuk penandatanganan tanpa kunci. |