cosign verifying/verify.md documents deprecated CA flags (--certificate-chain / --ca-roots / --ca-intermediates)

[mailnike]

Page

content/en/cosign/verifying/verify.md (lines ~84-99)

Problem

The "verify against a custom CA" section instructs users to use --certificate-chain, --ca-roots, and --ca-intermediates. All three flags are now deprecated in cosign in favor of --trusted-root, so the documented workflow steers users toward a deprecated verification path.

Evidence (cosign cmd/cosign/cli/options/certificate.go, current main)

• MarkDeprecated("certificate-chain", "please use --trusted-root to provide the certificate chain")
• MarkDeprecated("ca-roots", "please use --trusted-root to provide CA certificates")
• MarkDeprecated("ca-intermediates", "please use --trusted-root to provide CA certificates")
• (also certificate and sct are deprecated toward the bundle/trusted-root workflow)

The docs currently show, e.g.:

cosign verify --certificate-chain chain.crt --certificate-oidc-issuer ... --certificate-identity ...
cosign verify --ca-roots ca-roots.pem --ca-intermediates ca-intermediates ...

Why this is issue-grade (not a one-line fix)

The replacement --trusted-root flag takes a Sigstore trusted-root JSON, which is a materially different UX from passing PEM chain/roots/intermediates files. Rewriting the section correctly (how to obtain/construct the trusted-root, and whether to keep the deprecated flags documented as legacy) needs a maintainer decision. Happy to open a PR once the preferred direction is confirmed.

Suggested direction

Update the custom-CA verification section to document the --trusted-root workflow as the primary path, and mark the --certificate-chain / --ca-roots / --ca-intermediates examples as deprecated/legacy.