PackageCommands (7 of 16)

PackageCommandsclassdataclass#

Re-exported from ocx_sdk._clientView source

signmethod#

View source

def sign(ref: PackageLike, *, tags: Iterable[str] | None = None, tags_file: str | Path | None = None, platform: str | None = None, signature_format: SignatureFormat | None = None, key: str | None = None, rekor_upload: bool | None = None, fulcio_url: str | None = None, rekor_url: str | None = None, identity_token_file: str | Path | None = None, identity_token_stdin: bool = False, no_tty: bool = False, no_cache: bool = False, timeout: MaybeTimeout = UNSET, retry: MaybeRetry = UNSET) -> SignatureReport | SweepReport

Sign a package reference with cosign/Sigstore (C-011).

Three call shapes, one method (D2): tags or tags_file sweeps every matching tag and returns a SweepReport; neither signs ref alone and returns a SignatureReport.

mutating=True (D5) — retries are off by default; auto-retrying a Rekor-unavailable failure would amplify the public instance’s rate limiting (D6).

A --signature-format both run where one leg lands and one fails exits non-zero carrying a full report: catch OcxProcessError, recover it with partial_report(err), and parse with SignatureReport.from_json (D10) — SignatureLegReport.error names which leg died.

key and keyless signing are mutually exclusive with each other’s machinery, not just in spirit. Four flags refuse key outright — fulcio_url, identity_token_file, identity_token_stdin, and no_tty. Separately, rekor_upload=False (--no-rekor-upload) requires key — the opposite direction: it is meaningless for keyless signing, which cannot skip Rekor. And independently of key entirely, identity_token_file and identity_token_stdin conflict with each other — two ways to supply one token.

Parameters

Name	Type	Default	Description
ref	PackageLike	required	The package reference to sign.
tags	Iterable[str] | None	None	Sweep these tags instead of signing ref directly. Mutually exclusive with platform. Unions with tags_file when both are given — sweeping is triggered by either, not a choice between them. An empty sequence is refused: tags=None is how you act on ref itself.
tags_file	str | Path | None	None	Sweep the tags listed in this file. Mutually exclusive with platform. Unions with tags — see above.
platform	str | None	None	Sign one platform’s manifest. Refused alongside tags or tags_file.
signature_format	SignatureFormat | None	None	Which signature format(s) to produce.
key	str | None	None	A key reference — file:// or env://, the two backends ocx 0.6 implements. A bare path is read as file://. awskms://, gcpkms://, azurekms://, hashivault:// and k8s:// parse and are then refused with exit 85 (UnsupportedKeyBackendError), so no configuration makes them work. None signs keyless, against Fulcio. Conflicts with fulcio_url, identity_token_file, identity_token_stdin, and no_tty.
rekor_upload	bool | None	None	Upload the signature to the transparency log. False (--no-rekor-upload) is valid only alongside key.
fulcio_url	str | None	None	A non-default Fulcio instance. Conflicts with key.
rekor_url	str | None	None	A non-default Rekor instance.
identity_token_file	str | Path | None	None	Read the OIDC identity token from this file, for keyless signing without an interactive browser flow. Conflicts with key and with identity_token_stdin.
identity_token_stdin	bool	False	Read the OIDC identity token from stdin. Conflicts with key and with identity_token_file.
no_tty	bool	False	Suppress the interactive TTY prompt. Conflicts with key.
no_cache	bool	False	Skip ocx’s signing cache.
timeout	MaybeTimeout	UNSET	Seconds per attempt. Omitted takes the config’s.
retry	MaybeRetry	UNSET	Retry policy. Defaults to no retries.

Returns

SignatureReport | SweepReport

A SignatureReport for a single signing, or a SweepReport

SignatureReport | SweepReport

when tags/tags_file swept multiple.

Raises

ValueError

tags was empty; platform was given alongside tags/tags_file; key was given alongside fulcio_url, identity_token_file, identity_token_stdin, or no_tty; identity_token_file and identity_token_stdin were both given; or rekor_upload=False was given without key.

OcxProcessError

A non-zero exit — see the partial-failure note above for how to recover a report from one.