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) | Standard | File |
|---|---|---|
| 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.
| Part | CycloneDX | SPDX |
|---|---|---|
| The project | The metadata component: the repository's path, with the commit as its version | A package named after the repository, with the commit as its version and default branch <name> as its source; the document DESCRIBES it |
| Each dependency | A 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 withAND; a license without an SPDX ID by its name. - SPDX: the declared license expression (several joined with
AND), orNOASSERTIONwhen it is not known or has no SPDX ID. The concluded license is alwaysNOASSERTION.
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.
| Answer | When |
|---|---|
200 | The 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 |
400 | format must be cyclonedx or spdx |
404 | The project does not exist |
409 | this 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.
Related pages
- Project analysis: what the SBOM is built from.
- Project page → SBOM.
- Licenses: checking licenses on merge requests.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →