Exporting CycloneDX SBOMs from GitLab for customers and regulators
When a customer, auditor or regulator asks for a software bill of materials (SBOM) for a product built in self-managed GitLab, the answer starts with the dependency list. GitLab can export that list in CycloneDX, JSON and CSV formats, but the export is only as complete as the dependency data behind it. At a practical level, an SBOM names each component, its version and its license, so the recipient can see what the product is made of and which terms apply. Teams usually need one for customer due diligence, procurement reviews, regulatory requests and their own internal inventory. Each of those readers asks different questions, so decide early which fields and formats they need.
Before the work is scoped, confirm two things. First, the export tier: treat SBOM export as an Ultimate capability and check it against the current tier comparison on the GitLab pricing page for your edition and version before promising the output to a customer. Second, the scan prerequisites: the dependency list is built from dependency scanning results, so a project that has never run dependency scanning will export little or nothing useful. Confirm which projects, default branches and package ecosystems the scanners cover, and which ones use build systems or languages that the scanners analyze only partly.
Scope the engagement around the gaps the export cannot show. An SBOM lists what the scanners detected, so vendored code, copied libraries and container base images may be absent or only partly described unless they are scanned separately. Ask the customer or auditor which product, release and branch the SBOM must describe, and whether they need a separate component list for each release. Plan for the export to recur: each release needs its own SBOM, so the scanning and export steps belong in the release pipeline, and each sale does not start with a manual report. Confirm these points in writing before the build plan is fixed.
Which export format fits which request
This table compares the three SBOM export formats by who usually consumes them, what each suits and what to verify before sending. Read it as a starting point for matching a request to a format, then confirm the receiving party's required fields against a sample export from your own instance. The main takeaway is that the format should follow the consumer's tooling, not the other way around.
| Format | Typical consumer | Good for | Check before sending |
|---|---|---|---|
| CycloneDX | Customers and regulators with SBOM tooling that reads the CycloneDX specification | Machine-readable component inventories for intake into vulnerability and license tools | Confirm the spec version the recipient accepts and validate the file against it |
| JSON | Internal security teams and engineers building their own parsing or dashboards | Feeding pipelines, ticketing and custom reports where the full structure is needed | Ask the recipient which fields they read, then inspect a sample export to confirm those fields are present |
| CSV | Procurement, compliance reviewers and auditors working in spreadsheets | Quick review, sorting and filtering of components, versions and licenses | Check column headers and encoding, and confirm the reviewer does not need nested or relational data |
| Mixed request | Customers asking for both a standard SBOM and a human-readable list | Sending a standard file plus a summary without maintaining two sources of truth | Generate both from the same dependency list snapshot and record the date and project it covers |
Setting up SBOM export on a self-managed instance
This sequence confirms your GitLab tier, runs dependency scanning on each in-scope project, checks the dependency list and licenses, and produces exports you can compare against your own package manifests before anything leaves your organization.
Confirm the instance tier and SBOM export access
An administrator checks the license on the self-managed instance and confirms that the tier includes dependency scanning and SBOM export. The GitLab pricing page lists dependency scanning, SBOM-related software supply chain features and compliance features under Ultimate, so Free and Premium instances may not expose the export at all. Record the tier, the license expiry date and the GitLab version, because menu locations and export options can change between releases. Confirm these details against your own version's documentation before you plan the rest of the work. The output is a short written record of tier, version and export availability.
Inventory the in-scope projects and default branches
The security or compliance lead and the project owners agree which projects, groups and default branches the SBOM covers. Exclude archived projects, forks and sandboxes only where the written scope says so, and note which projects use lockfiles, manifests or vendored dependencies. Each dependency scan reads the default branch, so a project whose default branch is stale or unused will report stale components. The output is a list of project paths, default branch names and the package ecosystems each project uses.
Enable and run dependency scanning on the default branch
A maintainer adds the dependency scanning template to each in-scope project's CI/CD configuration, or applies it through a group-level setting where your instance supports that. The pipeline must run on the default branch so the dependency list reflects the code that ships. Check that the job completes without errors, that it reads the expected manifest and lockfile paths, and that it does not skip ecosystems your team uses. The output is a successful default-branch pipeline with a dependency scanning job in its log.
Verify components and licenses in the dependency list
A security engineer opens the project's dependency list and filters by package manager. Confirm that direct and transitive components appear, that versions are populated, and that license fields are filled for most packages. Empty license fields do not mean a package is unlicensed, so mark them for manual review rather than assuming a result. The output is a reviewed list with a short note of gaps, unknown licenses and ecosystems that did not report.
Export the SBOM in each required format
From the project, and from the group level where your version offers it, a reviewer generates the SBOM in each format the customer or regulator requires. Confirm which formats your version offers, including CycloneDX in JSON and any CSV option, by checking the current GitLab documentation for your release. Save each file with the project path, commit SHA and export time in its name so it can be traced later. The output is one file per format and scope, stored in your evidence location.
Compare exported contents against package manifests
An engineer compares the exported component list against the project's lockfiles and manifests, such as package-lock.json, go.sum or requirements files, and counts components per ecosystem. Differences usually come from unsupported ecosystems, excluded dev dependencies, vendored code or a scan that ran on an older commit. Confirm that CycloneDX fields such as component name, version, package URL and license are present in the export. Record each difference and its explanation. The output is a signed-off comparison note that states what the SBOM does and does not cover.
What each audience needs from an SBOM export
Customers and procurement teams usually ask for an SBOM during onboarding, contract review or a periodic supplier questionnaire. They want to know which components ship in the product they are buying, which versions they are, and whether any license terms conflict with their own use. The request is often narrow, such as one product or one release, so the export should be scoped to that artifact rather than an entire group of projects.
- Format: Provide CycloneDX JSON for tooling that ingests it, and a CSV summary if the buyer's reviewers work in spreadsheets.
- Fields: Component name, version, package URL, license identifier and the project or release the list belongs to.
- Refresh: Regenerate the export for each release the customer receives, not on a fixed calendar.
- Evidence: Attach the export date, the project and branch or tag it came from, and the scanner version that produced the dependency list.
- Caveats: State which dependencies were excluded, such as build-only tooling, so the buyer does not assume the list is complete when it is not.
Before sending, confirm with your legal or contracts team what the customer agreement says about SBOM delivery and whether any obligations apply in the markets where they operate.
Regulators and auditors ask for an SBOM as part of a broader review of how software is built and maintained. Their questions tend to focus on whether the list is traceable to a specific build, whether it can be reproduced later, and whether the organization can show when it was generated. Obligations differ by sector and jurisdiction, so the specific deadlines, formats and scope must come from counsel or the relevant authority, not from this page.
- Format: Expect requests for a standard machine-readable format, usually CycloneDX or SPDX, and the file must be retained unchanged.
- Fields: Component identifiers, versions, supplier where known, and hash or package URL data that lets a reviewer match components to artifacts.
- Refresh: Keep a dated export for each released version, and retain prior versions so historical builds can be examined.
- Evidence: Record the pipeline or job that produced the export, the commit it was generated from, and the scanner version and vulnerability database date.
- Chain of custody: Store exports in a location with access logs and retention rules that match your records policy.
Ask your compliance lead or external counsel to confirm which regulator or framework applies and what they will accept as evidence before you design the export process.
Internal security and platform teams use SBOMs day to day, to answer "are we affected" when a new advisory is published and to decide which projects need attention first. Their requests are frequent and cross many projects, so the export process needs to be automated and filterable by group, project and license rather than run by hand for each request.
- Format: Keep CycloneDX JSON as the working format for tooling, and use CSV for quick filtering by license or component name.
- Fields: Include dependency name, version, license, the project path and the pipeline that last scanned it, so triage can start from the export alone.
- Refresh: Schedule exports after dependency scanning completes on default branches, and generate them on demand for incident response.
- Evidence: Keep the export with its generation timestamp and scanner version, so findings can be compared across time when advisories change.
- Ownership: Name an owner for each project's export so stale or failed exports are noticed.
Confirm with your platform team which exports your vulnerability management tooling can consume and whether the self-managed instance has the scanners and advisory data it needs to run without outside access.
Security and handling of exported SBOMs
Each SBOM export carries the sensitivity of your internal inventory, so handling rules matter as much as the file format. The cards below cover who can export, how files are transferred and stored, and how to tell whether a file still reflects your code.
Inventories help attackers too
An SBOM lists every component and version in a project, which gives an attacker a ready map of known weaknesses in your software. Treat each export as confidential, share it only through encrypted channels with named recipients, and keep it out of tickets or chat threads that many people can read. Ask customers and regulators which handling terms they require before you send the file.
Timestamp and scope every file
An export reflects the dependency list at the moment it was produced, so new commits, merges and updated advisories can make it stale quickly. Record the export date, the project or group, the branch or commit, and the pipeline that produced the file, either in the file name or in an accompanying note. Regenerate the file before each audit or customer submission, and do not reuse an older copy.
Review license data before relying on it
License fields are only as complete as the metadata the scanners could read, so some components may show missing or unknown license entries. Have legal or open-source compliance staff review those entries, and any unexpected values, before the list supports a distribution or procurement decision. Record in the handover which fields were reviewed and who approved them.
Limit who can export
Creating and downloading an SBOM depends on the permissions a user holds on the project, so broad membership can expose inventories to people who never need them. Grant export and download rights through named project roles, keep the list of holders short, and review membership on a fixed schedule. Confirm in the current GitLab documentation which role can run the export and which can download the resulting artifacts.
Store exports under retention rules
Downloaded SBOMs tend to spread into email, shared drives and laptops, well outside the access controls on the source project. Keep one controlled location with restricted access, a written retention period, and a deletion step that runs on schedule. Also check the expiry settings on pipeline artifacts, because CI copies can outlive the file you meant to keep.
Confirm offline prerequisites early
On air-gapped instances, dependency scanning may depend on analyzer images and a vulnerability database that sit inside your network, and an export will not work until they are in place. Confirm with your administrators which mirrors, package sources and update routes exist, then test a run on a non-production project well before any customer or regulator deadline. GitLab documents separate guidance for offline scanners, which is the place to start.
Questions teams ask before exporting SBOMs from GitLab
What does SBOM export cost, and which parts are one-time versus recurring?
The cost is mostly labor plus licensing, and the licensing decision comes first. The GitLab pricing page lists application security testing and software supply chain security under Ultimate, which is custom priced, while Free costs 0 dollars and Premium costs 29 US dollars per user per month billed annually. Dependency scanning that feeds the dependency list is an Ultimate capability, so confirm your tier before scoping. One-time work includes configuring scanning templates, testing the export and building the handover. Recurring costs include Ultimate subscription seats, periodic re-exports for audits or customer requests, and keeping scanners current. Ask any partner for a written quote that separates these lines and states who pays for licenses, which are billed by GitLab directly.
How long does initial setup take, and what drives the duration?
Duration depends on scope, not on a fixed template, so ask for a timeline tied to a written scope. The main drivers are the number of projects that need dependency scanning, the language and package manager mix, whether projects already run pipelines, and whether the instance is offline. Projects with no lockfiles or with unusual build tooling take longer to validate. Air-gapped instances add work to mirror analyzer images and advisory data before any scan can run. A useful quote states the project count, the sample projects used for acceptance and the export formats required. Confirm in writing whether the timeline includes re-running scans after fixes.
What do we need from our own team before the work starts?
You need repository owners who can confirm which projects are in scope and which dependency manifests are authoritative, plus a GitLab administrator who can enable scanning, manage CI/CD configuration and grant access to the export. Someone must also decide the receiving format before work begins. CycloneDX, JSON and CSV serve different consumers: tooling and customer portals often want CycloneDX, spreadsheets and internal reviews often want CSV, and JSON is common for automation. Name the person who will accept the output and the license data they need, since legal teams often ask about license fields. Agree on who owns the pipeline changes after handover.
Can our internal team produce SBOMs from GitLab without outside help?
Yes, a capable internal team can do it, provided it has GitLab administration skills, access to the Ultimate features, and time to validate results. The hard parts are not the export itself but confirming that dependency scanning runs on every relevant project, that results are complete for each language, and that the output is accepted by the people who receive it. Teams with few GitLab administrators, many legacy projects or offline constraints often choose a partner for the setup and acceptance testing, then keep the routine export internally. Whichever route you choose, write down who maintains the scanning configuration after go-live.
How should we handle projects where the dependency data is incomplete?
Treat incomplete data as a finding to document, not a gap to hide. Common causes include missing lockfiles, dependencies resolved only at build time, unsupported package managers, vendored code and projects that have never run a successful pipeline. For each affected project, record what the export covers, what it does not, and the reason. Where possible, add lockfiles or a documented manifest and rerun the scan. Where a project cannot be made complete, state the limitation in the SBOM metadata or accompanying note so a customer or regulator does not read the file as exhaustive. Ask your provider to list these exceptions in the acceptance report.
Does an SBOM export prove compliance with a standard or regulation?
No. An SBOM export is evidence of the software components a build contained, and it supports a compliance program, but it does not prove compliance on its own. Independent auditors and certification bodies decide whether controls are met, and DeployOpen prepares systems, controls and evidence for those assessments without issuing audit reports or certifications. Ask which requirement each export supports, how the files are retained, how versions are tied to releases and who can reproduce an export on request. Confirm with your assessor which artifacts they expect before you build the process.
What should we request in a written quote for SBOM export?
Ask for a fixed scope that names the GitLab instance, the projects in scope, the export formats, the license data fields and the acceptance criteria. The quote should list one-time deliverables such as scanner configuration, validation and documentation, and separately list any recurring work such as periodic exports or retainer support. Ask how offline constraints are handled, what happens when findings need manual review and which GitLab tier is assumed. Confirm that licensing costs are excluded or included in writing. Most fixed-scope engagements are agreed in writing before work starts, so require the same for timelines and exceptions.
Why does dependency scanning need to run before an export is useful?
An SBOM export reads results that the dependency scanner has already produced, so a project without a completed scan has nothing to export. Engineers should confirm the scanning job runs on the default branch and on the release branches that customers receive, because an export from an old branch can misrepresent the shipped product. Check that scan results are current after advisory updates and that the export references the commit or tag it describes. These checks are easy to skip and are the most common reason exports disagree with what was deployed.
Limits to confirm in your environment
CycloneDX export depends on your GitLab edition, release, package managers and the offline data you can load. Each limit below is something to confirm against your own instance before you promise an SBOM to a customer or regulator.
Tier and release that include export
Confirm that SBOM export is included in the tier you license and in the exact GitLab release you run. The GitLab pricing page places software supply chain security and application security testing in Ultimate, but the feature matrix moves between releases, so check the export feature against your own version rather than assuming it from the tier name. Ask your GitLab account contact to confirm it in writing for your deployment.
Package managers and lockfile coverage
An SBOM is only as complete as the dependency list behind it. Check every package manager and lockfile format in your stack against the dependency scanning analyzers available to your release. Projects that use unsupported ecosystems, vendored code or build tools that do not write a lockfile may produce partial output. Run a test export on one representative project from each ecosystem and compare the component count with your own inventory.
Format versions the recipient accepts
Export format and specification version must match what your customer or regulator will parse. Ask the recipient which CycloneDX specification version and encoding they accept, then confirm that your GitLab release produces that version. Do not assume the newest specification is accepted downstream. Record the version in your release evidence so the file can be reproduced later.
Group or instance level export scope
Confirm whether your release lets you export at project, group or instance level, and who holds the permission to run each export. An instance-level SBOM for an organization with many groups may require several exports that you then merge, which changes how you prove completeness. Test with a group that has archived or inactive projects to see whether those are included.
Advisory and analyzer data on air-gapped instances
Offline instances do not fetch advisory databases or analyzer images on their own. Confirm how your team will import the vulnerability and advisory data, how often it must be refreshed, and whether the analyzers that generate the dependency list can run without internet access. Follow the GitLab offline environments guidance for the mirroring steps, and confirm that the dependency data on an isolated instance is as current as your recipient expects.
Fields the recipient expects
Check whether the exported file includes the license, supplier, hash, version and package URL fields your recipient needs. License data may be incomplete for some components, and the fields present can vary by format and release. Compare a sample export with the recipient's required field list, and document any field that is missing or empty so you can explain it or fill it from another source.
How DeployOpen scopes and delivers SBOM export work
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including GitLab. For SBOM export, we start from a written scope that names the projects, formats, recipients and evidence the export must serve, then build and verify the export path in your environment.
How we scope
- Confirm which projects, groups and dependency lists feed the CycloneDX export and which GitLab tier your instance uses
- Agree in writing which formats, including CycloneDX, JSON and CSV, and which license fields each recipient needs
- Record what dependency scanning must run first, and which pipelines and analyzers must be in place before exports are trusted
How we build
- Configure dependency scanning and the export path on your self-managed instance, including any offline analyzer mirrors your network requires
- Test exports against known projects and compare component counts, versions and license data with what your team expects
- Document the export procedure, the job or API calls used, and the storage location for generated files
How we hand over
- Deliver a runbook covering how to generate, review, store and send an SBOM for a given release
- Walk your engineers and compliance leads through the export, the known gaps in dependency data and the checks to repeat
- Provide written deliverables defined in the fixed scope, so acceptance is based on agreed criteria
How we support
- Ongoing support, GitLab upgrades and continuous testing are available as retainers after handover
- Review export behavior after GitLab upgrades, since release changes can affect dependency data and formats
- Confirm current GitLab version guidance and upgrade stops with your team before changing the export path in production
