Skip to main content
Video tutorial · 0:58

SBOM export

A software bill of materials (SBOM) lists what a piece of software is made of. Merge Pilot exports one for each analysed project: the dependencies its default branch uses, as of the last project analysis, with their licenses. Customers, auditors and security tools read it in one of two standard formats.

Exporting​

On the project's page, Security tab, Export SBOM, then the format (the button shows once an analysis of the project has completed: while the first one runs, or when it failed, there is nothing to export yet):

Format (label in the UI)StandardFile
CycloneDX (JSON)CycloneDX 1.7, JSON<project>-<commit>.cdx.json
SPDX 2.3 (JSON)SPDX 2.3, JSON<project>-<commit>.spdx.json

<project> is the repository's path with / replaced by -; <commit> the first 8 characters of the commit the analysis read.

A project whose dependencies have never been read cannot be exported yet (through the API too): this project has not been analysed yet: run an analysis first.

What it holds​

The SBOM is built from what Merge Pilot recorded about the default branch at its last analysis, not read fresh from the repository: run an analysis first for an up-to-date one.

PartCycloneDXSPDX
The projectThe metadata component: the repository's path, with the commit as its versionA package named after the repository, with the commit as its version and default branch <name> as its source; the document DESCRIBES it
Each dependencyA library component: name, version, package URL (purl) when known, licenses, and the properties merge-pilot:ecosystem and merge-pilot:manifest (one per manifest that lists it)A package: name, version, the purl as an external reference when known, the declared license, and manifests: … as its source; the project DEPENDS_ON it

| The tool | Merge Pilot and its version | Creator Tool: Merge Pilot-<version> | | When | The time of the export | The time of the export |

A purl is written only when one can be built for the package. A dependency without one has no purl in CycloneDX (its bom-ref is still its own) and no package-manager reference in SPDX; Merge Pilot never writes a made-up value in its place.

Every package version a manifest of the branch lists is included once, whichever manifests list it (development dependencies and transitive ones included, as the manifests list them). Dependencies named by a version range, without an exact version, are included with the range as their version.

Licenses​

Licenses are those the last completed analysis found (from deps.dev). Retention never removes that analysis's details, so an SBOM keeps its licenses however old the analysis is:

  • CycloneDX: plain SPDX license IDs as licenses; when a package declares an expression (MIT OR Apache-2.0) or several licenses with one, they are written as one expression joined with AND; a license without an SPDX ID by its name.
  • SPDX: the declared license expression (several joined with AND), or NOASSERTION when it is not known or has no SPDX ID. The concluded license is always NOASSERTION.

A dependency the analysis found no license for has none in the SBOM.

Incomplete SBOMs​

When the last analysis could not read every manifest of the branch, the SBOM may leave dependencies out. It says so:

  • in the document: the CycloneDX metadata property merge-pilot:incomplete, or the SPDX creator comment, Incomplete: Merge Pilot could not read every manifest of the branch (…); dependencies may be missing., with the reasons in brackets (tree_truncated:…, max_manifests_exceeded:50, manifests_unreadable:N; see Project analysis → Results may be incomplete);
  • in the page: Exported, but not every manifest of the branch could be read: the SBOM may leave dependencies out (see the analysis).;
  • in the API: the header X-SBOM-Incomplete: true.

Who may export​

Everyone in the company: users, auditors, policy managers, company admins, and platform admins. Exporting changes nothing.

API​

GET /api/v1/projects/{id}/sbom?format=cyclonedx (the default) or format=spdx.

AnswerWhen
200The document, as application/vnd.cyclonedx+json or application/spdx+json, with a Content-Disposition file name, and X-SBOM-Incomplete: true when it may leave dependencies out
400format must be cyclonedx or spdx
404The project does not exist
409this project has not been analysed yet: run an analysis first

Audit​

Each export writes sbom_exported to the audit log, by the person who exported it, with the format, the commit and the number of components. See Audit log → Projects.

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Vulnerability Inventory and SBOMYouTube ↗