Populate attestation for Docker images via OCI Referrers API (GCR/AR)

[kornelwencek-esky]

Tell us more.

We run an attestation pipeline on Google Artifact Registry (Binary
Authorization): each attested digest gets an AR "attachment", reachable via
the standard OCI 1.1 Distribution Spec Referrers API
(GET /v2/<name>/referrers/<digest>).

Renovate's docker datasource reads AR directly, so it proposes bumps to
whatever tag/digest exists there — regardless of whether it's actually
attested. We hit this concretely: a Renovate-triggered CI build on an open,
unmerged PR pushed a real digest to AR before attestation ran; a downstream
Renovate instance picked up that unattested digest and opened a PR for it.

This is the same shape as #37258 / #37268 (npm losing dist.attestations),
which added a generic attestation?: boolean field to Release plus a
PR-body warning — already datasource-agnostic, it just needs docker to
populate release.attestation too.

I have a draft implementation that checks referrers only for the latest
tag (mirrors the existing sourceUrl/gitRef label lookup, one extra request
scoped to latest), is presence-based (any referrer counts, not filtered by
artifactType), is scoped to Google Container/Artifact Registry for now,
and is gated behind an opt-in RENOVATE_X_DOCKER_CHECK_REFERRERS flag.

Before opening a PR, feedback welcome on:

1. Latest-tag only, or also the current version (needed for the existing
   warning to actually fire on upgrade)? Would require passing current-value
   context into getReleases(), which it doesn't get today.
2. Presence-based vs. filtering by artifactType (cosign/in-toto/SLSA)?
3. GCR/AR-only as a starting scope, or design for any OCI-referrers-capable
   registry from the start?
4. RENOVATE_X_ opt-in, or unconditional given it's one extra request on one
   tag?

Happy to open a draft PR with what I have once there's rough agreement on
direction.

Edit:
PR Draft: #44642

[jamietanna]

I think generally this is OK, however:

• the Docker datasource is already quite network-heavy or "expensive" as we've described it in the past. Adding this will add a lot more traffic
• the attestations we report in the npm datasource are - as you've seen - "presence" only. We don't validate them at all, and so they're maybe not as strong a recommendation as they could be
• I'd want to consider how we want to handle attestation metadata more generally - should we really be validating them? And then filtering out any releases that don't match the attestation? (That's more compute that Renovate needs to handle)
• we should probably do a before/after of the attestation status to at least check whether it was there and then removed

[kornelwencek-esky]

Thanks, this is genuinely useful pushback, changed my mind on a couple things here.

On the network cost - fair, I don't have a strong opinion on where the line is given the datasource is already heavy. My scoping (one extra request, one tag, opt-in) was meant to keep it cheap, but if that's still too much for getReleases(), maybe it shouldn't live there at all - could instead be checked once, right before a branch/PR actually gets created for a specific candidate, instead of on every lookup. Open to whichever hook point makes more sense to you.

On presence-only being weak - yeah, agreed, this is basically my question #2 from above. Actually verifying a signature/predicate is a much bigger job (crypto, key management, policy) and I don't think a first pass should try to do that. I'd rather just be upfront that it's informational, not verified, and say so in the docs.

On validating + filtering releases - this is the one I'd push back on a bit. npm doesn't filter unattested versions either, just warns, and I think that's the right call here too. We already lean on Binary Authorization as the actual enforcement at deploy time, so I'd rather Renovate stay a signal and not start deciding what's "valid" - that feels like it belongs to a policy tool (Kyverno, OPA, binauthz itself), not the dependency updater. But genuinely open if you see it differently.

On before/after - you're right, and it's my open question #1. Right now I only populate attestation for the latest tag, which doesn't actually make the existing "lost attestation" warning fire, since that needs the current version's status too and getReleases() has no idea what the current value is today. Not sure what the right way to thread that through is - is there an existing pattern for that in other datasources? Happy to make that the actual scope here if you can point me at it.

So overall I think the real PR is narrower than what I opened - warn on regression only, no filtering, informational/presence-only - and I'd like to figure out the right hook point before writing more code.

[kornelwencek-esky]

@jamietanna just noticed the PR got locked to collaborators, so I can't update the description or comment there myself. The reply above is the current, accurate scope: just surface whether an attestation-type referrer exists (presence only), nothing else - no verification, no filtering. Happy to update the PR body to match once it's unlocked, or if it's easier for a maintainer to just edit it directly, that works too.