The manifest jobs of the canonical project sign every gkg image digest that they publish. They
use keyless Sigstore cosign with the GitLab OIDC identity of the job. A signature proves that a
job of this project built the digest on the named ref. It does not prove a review.
Verify an image
Use cosign 3 or later. Replace <version> with the release:
cosign verify \
--certificate-identity "https://gitlab.com/gitlab-org/orbit/knowledge-graph//.gitlab-ci.yml@refs/tags/v<version>" \
--certificate-oidc-issuer https://gitlab.com \
registry.gitlab.com/gitlab-org/orbit/knowledge-graph/gkg:<version>Check: the command exits 0 and prints the certificate identity. The double slash before
.gitlab-ci.yml is part of the identity.
Tag identity and branch identity
Only a refs/tags/v<version> identity means a release. A refs/heads/<branch> identity does not
mean a release.
A policy pattern must match the full identity, with anchors at both ends:
^https://gitlab\.com/gitlab-org/orbit/knowledge-graph//\.gitlab-ci\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$.
Pin index digests, not platform digests. The platform manifests in an index have no signature.
Mirror a signed image
Warning
Use oras copy -r. Other tools copy the image without its signatures and still exit 0.
Check: run the verify command against the mirror.
Warning
Do not use cosign copy into a repository that holds signatures. It creates sha256-<digest>
tags with the names that the registry uses for signatures.
Keep signatures in the registry
Warning
Do not delete tags that match sha256-*, and do not let a cleanup policy match them. Each one
holds the signatures of an image digest.
When signing fails
A signing failure stops the manifest job (docker-manifest or release-manifest) before it
moves the final tags. Check the Sigstore status, then retry the
manifest job. A retry of an old release pipeline moves latest back to that release.