Pin a Flux OCIRepository by digest for production, and add signature verification. Flux documents that a digest in the reference takes precedence over every other field, and that a tag can point somewhere new tomorrow. Tags and semver ranges suit lower environments where you want updates to arrive on their own.
What an OCIRepository is
Flux can fetch Kubernetes manifests or Helm charts packaged as OCI artifacts from a container registry. The OCIRepository resource tells Flux where to look and which version to follow. Flux resolves the reference, records the digest, and builds an artifact from it.
In the Flux documentation, the URL field names the repository only. Specifying a tag or digest in the URL is not accepted. The version choice goes in a separate reference block.
Three reference options
The reference accepts a tag, a semver range, or a digest. Fields listed later take precedence over earlier ones. If you give none, Flux defaults to the latest tag.
| Option | Behavior | Risk if the registry or publisher misbehaves |
|---|---|---|
| tag | Follows one named tag | The tag can be re-pushed to different content |
| semver | Picks the highest tag in a range | A new tag in range is deployed without review |
| digest | Fixed content hash | Content cannot change under the same digest |
A digest is a hash of the content, so it describes exactly one artifact. That is the property you want when production must match what was reviewed.
Flux also offers a semver filter, a regular expression applied to tags before the range is resolved. It only takes effect when a semver range is set. Use it to ignore tags from other release lines in a shared repository.
Add verification
Pinning proves you got the same bytes. It does not prove the bytes came from the right publisher. Flux supports a verify block for Cosign and Notation signatures. You provide the provider, a secret holding trusted public keys, and for Cosign keyless flows, OIDC identity matchers.
A reasonable production setup combines both: a digest reference for sameness, plus verification so that a new digest is only accepted if it is signed by an identity you trust.
A practical update flow
- Staging follows a semver range, so new releases land there automatically.
- A job or a person records the digest that passed staging checks.
- A pull request changes the production reference to that digest.
- Verification confirms the signature before Flux uses the artifact.
This keeps humans in the loop at the one moment that matters, and the diff in the pull request is a single hash change plus the evidence you attach.
Be honest about the cost. Digests are unreadable, so reviewers need the release notes and scan results next to the change. Tools that open these pull requests can help, but check what each one supports for OCI sources before relying on it.
Where a scanner fits
Whatever you pin, you still need to know what is inside it. Safeguard's SBOM and dependency scanning can inventory the packaged charts and images, and policy gates can block a pull request that moves production to an artifact with a known problem. Confirm which artifact formats your scanner reads. A free scan is available at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen.
Look at how a dependency inventory lists versions and sources, then ask whether your OCI artifacts would appear in yours.
Quick check
Can I put the digest in the OCIRepository URL?
No. The Flux documentation says the URL field must not include a tag or digest. Put the digest in the reference block instead.
Does pinning a digest verify the publisher?
No. A digest fixes the content, not its origin. Use the verify block with Cosign or Notation to check who signed it.
Sources
Last reviewed: 19 October 2026.
