feat(ci): send a released version's documents to Dependency-Track

[nikzen]

Why

A document attached to a release answers what a version shipped, to whoever thinks to look for it. It cannot answer the other direction: a component became a problem today, and which of the versions still out there holds it. That
question arrives without warning, is asked of every release at once, and is the one a regulator asks. Answering it needs the documents somewhere that keeps them, which is what Dependency-Track is for.

Stacked on #81, which switches these documents to CycloneDX — the only format Dependency-Track reads.

What changed

Each document is told what it describes. syft names the image it read and stops there, so the document carries no identity for the artefact it is about. A digest is the one name for an image that cannot drift, and it exists only once
the registry holds the image, so it is written in between the push and the signature: the attestation, the release asset and the tracker then all agree. The repository and the run go in beside it, because a digest still does not say where the thing came from. The lockfile document has no image of its own to point at and names the commit its packages were read at instead.

Dependency-Track reads purl, cpe, the supplier and the external references straight out of metadata.component on upload — verified against a live instance — so this needs no second call and no right to modify anything.

A released version's documents are sent to the tracker. Only released versions: nobody asks that question of a nightly.

Each platform image gets a line of its own, under a node for the index, under one for the product:

famedly-control-client
├── famedly-control-client-image
│   ├── famedly-control-client-amd64
│   └── famedly-control-client-arm64
└── famedly-control-client-source

A platform image is a separate artefact holding different bytes, so a single document over the index could only ever describe one of them, and each line keeps a history of its own. The analysis recorded against the previous version
is carried over by cloning it, or every release would start its triage from nothing — Dependency-Track offers no other way to inherit it.

Names are the short ones, because the registry reference is now in the document.

What a repository needs

DEPENDENCY_TRACK_URL as a variable and dependency_track_api_key as a secret. Where the variable is unset the step is skipped, so nothing is required of a repository with no tracker to tell.

Verification

Both workflows generated in famedly-control against this branch, then the generated scripts run verbatim against a live Dependency-Track 5.0.5 instance across two releases of a throwaway image:

• The tree came out as above, with the product, index and platform lines nested and their aggregation logic as intended.
• The leaves arrived as CONTAINER and the lockfile document as APPLICATION, with the supplier, the purl carrying digest, registry, architecture and tag, and both external references.
• On the second release isLatest moved by itself, both recorded verdicts were inherited, and a dependency bump planted for the purpose surfaced as 16 open findings.
• The same bump fails the existing grype gate, so nothing reaches the tracker that the pipeline would have let through silently.

Made with Cursor

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e4f98bc. Configure here.}