Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Project versions

What a project version is and why is explained in Concepts; how to use them, in Track several versions of a product. Uploads name versions with the upload API’s version and latest parameters.

States

Every version of a project has two flags:

Flag
latestExactly one version of a project is the latest: the one the project page, the read API and the VEX export show when they are not asked for another, and the one a new version inherits its findings from
activeWhether runs evaluate the version. A new version is active. The latest version is always active

An inactive version is kept as it was when it was made inactive:

Active versionInactive version
Evaluated by runs (findings opened, fixed, reopened; ignores expire)✓
Counted on the organization page and in the projects of the read API✓
Counted in the metrics (nanobom_open_findings, nanobom_open_findings_known_exploited)✓
Found by component searches✓With Include inactive versions (interface) or inactive=true (read API)
Listed in a finding’s Also affected (affected_components)✓
Notified: findings.new, known exploited, emails✓
Shown on the project page (Version filter, Versions table) and in /versions✓✓, marked inactive
Readable: findings, components, license violations, finding pages, VEX export✓✓
Listed in a finding’s Versions of this project (versions)✓✓, marked inactive

Staleness stays per project: an inactive version does not make its project stale.

Changes

ChangeHowRefused when
Make a version inactiveMake inactive in the project page’s Versions tableIt is the latest: mark another version latest first
Make a version active againMake active, or any upload to the versionThrough the interface only: the project already has 50 active versions (an upload makes room instead, see the cap)
Mark a version latestMake latest, or an upload with latest=true; an upload creating a version also makes it the latest unless latest=falseIt is inactive: make it active first (an upload with latest=true makes it active)
Delete a versionDelete, then tick the confirmation box and select Delete versionIt is the latest, or the project’s only version: delete the project instead

Changing versions takes the permission to delete projects: admins and owners (roles); viewers and members see the Versions table without its actions. There is no API to change versions besides uploads. A version made active in the interface is checked at once by a run of its project; otherwise the next run catches up. A run evaluates the versions active when it starts: a version made active, or created by an upload, while a run is in progress waits for the next run, and keeps its findings as they are until then.

Deleting a version deletes its components, dependency graph, upload history and findings with their history, in one transaction. Other versions keep theirs, including findings they inherited from the deleted one. Nothing else deletes a version, except deleting its project.

The error messages:

RefusalMessage
Making the latest version inactivethe latest version cannot be made inactive: mark another version latest first
Marking an inactive version latestan inactive version cannot be the latest: make it active first
Deleting the latest versionthe latest version cannot be deleted: mark another version latest first
Deleting the only versiona project keeps at least one version: delete the project instead
Making a version active past the capthis project already has 50 active versions: make one inactive first

The cap

A project has at most 50 active versions. When an upload would create a version, or make an inactive one active again, while the project already has 50, nanobom first makes one other version inactive, in the upload’s transaction, and the upload proceeds:

  • the active version whose last upload is the oldest goes, a version never uploaded to counting from its creation;
  • never the latest version, nor the version uploaded to;
  • the server logs it (version made inactive: the project reached its maximum of active versions, with the project and the version).

Inactive versions are never deleted automatically: a project that receives a new version name with every build keeps every build, the last 50 of them active.