GitLab SBOM-based dependency scanning

What GitLab SBOM-based dependency scanning does and when to set it up

If you need a current inventory of third-party components across your self-managed GitLab projects, SBOM-based dependency scanning is the approach to plan for. It builds a dependency list for each project from CycloneDX SBOMs, and it is an Ultimate capability, so the decision starts with your licensing rather than your pipeline templates. The older Gemnasium-based analyzer worked differently: it inspected dependency files and matched them against advisory data inside the scanner. The SBOM approach instead reads a software bill of materials that the build produces, so the inventory reflects what was actually built and packaged. Confirm with GitLab which package managers and lock file formats each approach covers for your languages before you assume either one is complete.

Teams usually need this in three situations. The first is approval policies, where a merge request or pipeline should be blocked or routed for review when a vulnerable component is introduced. The second is a customer or regulator request for an inventory of components in a delivered product, which needs an accurate, exportable list. The third is an offline or air-gapped instance, where advisory data and scanner images must be mirrored into your network before any scan can run. For that case, read GitLab's offline environments documentation early, because mirroring affects the scanner plan, not just the pipeline. Ask your GitLab administrator to confirm the Ultimate license is active on the instance before any project work begins.

The practical work is deciding scope and ownership. List the projects that produce deployable artifacts first, since those are the components your customers and auditors will ask about, and confirm which of them already generate SBOMs in their builds. Assign one owner for the dependency list so findings are triaged in one place. Plan for continuous rescans: a component that was clean at merge can later match a new advisory, so the dependency list should update when advisory data changes, not only when code changes. Confirm how often GitLab rescans and which advisory sources feed it on your version, because those details change between releases and should be taken from current GitLab documentation, not from this page.

Configuration choices and when each fits

This table compares the five decisions that shape a dependency scanning setup: tier, connectivity, scan trigger, template inclusion and merge gating. Read each row for what it changes and which team it suits, then confirm the open points with GitLab or your own environment before you commit to a design.

Decision	What it changes	When it fits
Tier	SBOM-based dependency scanning is part of Ultimate. Free and Premium do not include it, so choosing those tiers means no dependency scanning findings or dependency list from this method.	Teams that need dependency findings, the dependency list and policy enforcement. Confirm current feature availability on the GitLab pricing page before you buy.
Connected instance	Scanners can pull analyzer images and advisory data from GitLab-hosted sources during jobs. Advisory data stays current automatically.	Instances with outbound access that permits the required sources. Confirm the exact endpoints with your network and security team.
Offline instance	Analyzer images, advisory databases and any package mirrors must be brought in from inside your boundary. Updates become a planned transfer, not a background process.	Air-gapped or restricted networks. Plan the mirroring pipeline and an update cadence before the first scan, and check GitLab's offline guidance for scanners.
Scans on merge requests	Dependencies are checked against the proposed change, so new vulnerable packages surface during review before they reach the default branch.	Teams that want findings tied to a specific change and an early gate on new dependencies.
Scheduled scans on the default branch	The dependency list reflects what is actually on the default branch, and scheduled runs can pick up advisory changes between code changes.	Teams that want a current picture of the default branch even when no code changes. Pair with merge request scans for full coverage.
Project-level template inclusion	Each project adds the scanning template to its own pipeline configuration. Changes are made project by project and may drift across repositories.	Small estates or pilots, or teams with project owners who manage their own pipelines.
Group-level template inclusion	Scanning is defined once and applied across many projects, which makes consistency easier to show but moves change control to whoever owns the shared configuration.	Organizations that need the same scanning across many repositories and an auditable central definition.
Results gate merges through approval policies	Policies can require approval or block merges when defined findings appear. Blocking adds delay for developers and needs a clear exception process.	Teams with a defined vulnerability response standard. Start in a non-blocking mode where possible, and confirm the policy options available in your version.

How to set up SBOM-based dependency scanning step by step

This sequence takes a self-managed GitLab instance from confirmed Ultimate licensing to a dependency list fed by SBOM-based scanning, then rolls the scanning out through group settings and approval policies. Each step closes with a check you can run before moving on.

Confirm Ultimate licensing on the instance
An administrator checks the license in the Admin Area and confirms the subscription tier is Ultimate, because SBOM-based dependency scanning, the dependency list and the policy features that consume its results are Ultimate-only. Confirm the license covers the self-managed instance itself, not only a group namespace. Check the result in the Admin Area license view: the plan shown should read Ultimate and the expiry date should be later than your planned pilot. If the plan reads Premium or Free, stop here and resolve licensing with GitLab before continuing, since later steps will not produce the expected features.
Confirm runners can reach the analyzers
The platform team confirms that the GitLab Runners used for the pilot can pull the dependency scanning analyzer images, either from the public registry on a connected network or from an internal mirror on an air-gapped one. For offline instances, the mirroring and prefix settings in GitLab's offline guidance must be in place first. Ask the runner owners to test a plain image pull from a runner host and from the job environment, not only from a workstation. Done when a test job on the pilot runner pulls the analyzer image without a network or authentication error. Exact image paths and variables are in the official dependency scanning documentation.
Include the dependency scanning template in a pilot project
A developer or platform engineer picks one representative project, ideally one with a lockfile or package manifest that the team already maintains, and adds the SBOM-based dependency scanning template to its CI/CD configuration. Use the template name exactly as written in the GitLab template reference for the current release, and avoid copying older examples that reference deprecated analyzers. Keep the pilot to a single project so that problems are traceable. Check the change by opening the pipeline editor and confirming the scanning job appears in the rendered configuration without YAML errors.
Run a pipeline and confirm the SBOM artifact
Trigger a pipeline on the default branch and let the dependency scanning job run to completion. The job should produce a CycloneDX SBOM as a job artifact alongside its report. Download the artifact or open the job's artifact browser to confirm the file exists and lists components that match your manifests. If the job fails, read the analyzer log first, since unsupported package managers, missing lockfiles and network blocks are the most common causes. Done when the artifact is present, non-empty and lists the direct and transitive packages you expect.
Check the dependency list is populated
Open the project's Dependency list under Secure and confirm the components from the SBOM appear with their versions, package managers and locations. Compare a sample of entries against your lockfile, including at least one transitive package and one package with a known advisory if the project has one. Verify that vulnerability counts link to the advisory records rather than appearing as bare numbers. Done when the list matches the pilot's dependencies closely enough that the team accepts it as the source for later policy decisions. Record any gaps, such as unsupported lockfile formats, so they can be resolved before rollout.
Confirm continuous rescans on advisory changes
Advisory data changes after a build passes, so confirm that the instance is set up to rescan existing dependency lists when the vulnerability database updates. On an offline instance, this depends on the advisory database mirror being refreshed on a schedule your team controls, so ask the platform team who owns that job and how often it runs. Trigger or wait for one update cycle, then check that a project with no new commits shows updated vulnerability status in its dependency list. Done when you can name the refresh mechanism and have observed a status change without a code push.
Roll out through group settings and approval policies
Once the pilot is accepted, enable the scanning template across the target groups, using group-level CI/CD configuration or a pipeline template that projects inherit, and then write merge request approval policies that reference the dependency scanning results. Start with a policy in warning or non-blocking form if your governance process allows it, then move to enforcement after the owners of affected projects have reviewed the first findings. Check the rollout by confirming that a new project in a target group receives the scan without manual setup, and that a test merge request with a policy-triggering vulnerability requires the expected approval. Policy syntax and scope options are documented in GitLab's approval policy reference.

How continuous rescans keep the dependency list current after advisories change

A dependency list built from a single pipeline run describes the components that existed on the day the pipeline ran, not the vulnerabilities known today. New advisories are published continuously, so a component that looked clean at merge can carry a known vulnerability a week later. Continuous rescanning closes that gap by re-evaluating the component data already stored for each project against updated vulnerability data, without requiring a new commit or a new pipeline. The point for your team is that a clean dependency list is a dated observation, and the rescan schedule decides how stale that observation can become.

Rescan timing is a trade-off between currency and instance load. Frequent rescans surface new advisories sooner but consume more processing and database capacity on the instance, which matters most on a shared self-managed installation serving many projects. Less frequent rescans reduce that load but widen the window in which a newly disclosed vulnerability is absent from the dependency list and from any approval policy that depends on it. Before you set expectations with security owners, confirm with GitLab how often rescans run, which events trigger them (for example, a database update or a project-level change), and whether they can be scoped or throttled on your instance size.

Air-gapped instances need a separate check. Vulnerability data on a disconnected network only changes when you import it, so a rescan there is only as current as your last approved data transfer. Confirm with GitLab's offline documentation how advisory data is delivered to an isolated instance, who owns that import, and how often it must happen to meet your policy. Then test the path end to end: import an update, confirm the dependency list reflects it, and check that the approval policies behave as expected. Record the import cadence as a control, since auditors will ask how quickly newly published advisories reached your dependency list.

Where dependency findings should gate merges and where they should only inform

Dependency findings are only useful if the team trusts what blocks a merge. Each decision below sets how strict a policy is, where it applies and what happens when no fix exists, so confirm how your GitLab version evaluates dependency results before you enforce anything.

Block merges on new critical findings

Gate merges only on newly introduced critical findings, not on the full backlog of existing vulnerabilities. A policy that fails every merge request because of old advisories teaches developers to look for workarounds. Check in your version whether the approval rule counts only findings introduced by the change, how it treats findings that are still unresolved on the default branch, and whether a critical severity match depends on the scanner's severity mapping.

Apply policies to protected branches

Scope blocking rules to protected branches and release paths, so feature branches keep moving while the code that ships is held to a stricter bar. Confirm whether your policy's branch targeting can match the branches you protect, and whether merge request approval rules and scan result policies both apply to the target branch that the merge request actually uses.

Scope policies to groups or projects

Attach policies at the group level when every project must meet the same rule, and at the project level when a service has its own risk profile. Broad scope spreads one policy across unrelated teams. Confirm how inheritance works in your GitLab version, which role is required to edit a policy, and how policy scope is evaluated for projects created after the policy was set.

Handle findings with no fix

Some advisories have no patched version yet, or the affected package is a transitive dependency your team cannot upgrade directly. Decide in advance whether these findings inform only, require a documented risk acceptance, or block until a fix exists. Confirm how the dependency list marks findings without a fixed version and whether your policy can exempt a specific vulnerability with an expiry date.

Handle license findings separately

License findings carry legal risk rather than exploitability, so they usually need a different owner and path than vulnerabilities. Keep license checks as informational or route them to legal review instead of blocking every merge on a license name. Confirm which license data your version reports for each component, how unknown licenses appear, and whether license policy is configurable separately from vulnerability rules.

Avoid conflicting policy links

When a project is linked to more than one security policy project, or a group policy and a project policy both apply, required approvals can stack or contradict each other. Keep one policy project per scope where possible and document which policies apply to each project. Confirm in your version how multiple linked policies combine, which one wins on conflict, and how to audit the effective policy for a given merge request.

Connected, offline and Gemnasium-era instances need different setups

A connected self-managed instance can reach the advisory sources that dependency scanning relies on, so most of the work is making sure network access, runner placement and licensing are in place before the first scan is enabled. Because the scanner gets advisory data at run time, the refresh cadence depends on your network policy as much as on GitLab configuration.

Egress rules: Confirm which advisory and package endpoints the runners and the GitLab instance must reach through your proxy, and allow them before you enable the template.
Runner placement: Decide which runners execute scan jobs and whether they sit in a network segment with the outbound access those jobs need.
Tier check: Dependency scanning and the dependency list belong to Ultimate, so confirm license coverage for every group in scope. The GitLab pricing page shows which features each tier includes.
Rescan triggers: Plan scheduled pipelines so projects are rescanned when advisories change, and confirm how the advisory data refreshes for your version.
TLS inspection: If a corporate proxy inspects outbound TLS, test whether the scanner's calls succeed and document the trust bundle it uses.

Check these settings against the dependency scanning documentation for your exact GitLab version before rollout, since analyzer behavior and required endpoints can change between releases.

Security and operational risks to plan for

SBOM-based dependency scanning creates a detailed inventory of your software, and it depends on runners, advisory data and upgrade timing that change over time. The cards below cover the decisions and checks that keep the scanning trustworthy and the inventory contained.

Component inventories visible to project access

The dependency list and the SBOMs built from it name every library and version in a project, which is useful to an attacker looking for known weaknesses. Anyone with access to the project can usually see this data, so check who holds Reporter and above roles on repositories that contain sensitive or regulated code. Decide whether SBOM export and dependency list access should be limited to security and compliance roles, and confirm how exported SBOM files are stored and shared outside GitLab.

Runner trust and job token scope

Dependency scanning runs as a CI/CD job, so the runner that executes it has access to the project's code and to any variables the job can read. Use runners dedicated to scanning jobs or isolated runners for protected branches, and confirm which runner executor type your fleet uses before enabling the template. Review the job token permissions that the scanning job receives, and avoid granting it access to other projects or groups it does not need.

Stale advisory data on offline instances

Scanners match components against vulnerability advisory data, and that data is only as current as the last update delivered to your instance. On an offline or air-gapped GitLab, advisory data and analyzer images must be mirrored on your own schedule, so a missed sync means new advisories go unreported. Set an owner and a cadence for mirroring, and confirm with GitLab's offline documentation how the advisory data is delivered to your environment before relying on empty results.

False positives and triage workload

A dependency scan can flag components that are present but not reachable in your code, or flag issues that your vendor has already mitigated, and each finding needs a triage decision. Without a rule for who triages, which states count as resolved, and how dismissals are recorded, the backlog grows and developers begin ignoring the report. Agree on dismissal reasons and an owner for the vulnerability list before the first scan is made blocking.

Upgrade timing against release cadence

GitLab ships a minor release on the third Thursday of each month and patch releases twice a month, and only the current stable release receives bug fixes. Security fixes are also backported to the previous two monthly releases, so an instance that falls behind can lose both scanner fixes and the vulnerability data that depends on them. Set a patching window that keeps the instance inside the supported releases and track the release cadence against your change calendar.

Required upgrade stops change scanner behavior

GitLab requires upgrades to pass through required stops, which since GitLab 17.5 fall at versions x.2, x.5, x.8 and x.11. Scanner templates, report formats and policy syntax can change between releases, so a jump across a stop can alter what a pipeline reports or blocks. Plan each upgrade on a staging instance, rerun the scanning jobs against known test components, and compare findings before the production upgrade.

What to confirm in your environment before you rely on dependency scanning

Confirm three things before you treat dependency scanning as a control: that your language ecosystems and lockfile formats are covered, that your licence includes the tier that provides the feature, and that advisory data reaches your instance. Start with tier entitlement. GitLab's pricing page places application security testing and software supply chain security in Ultimate, which is custom priced, while all three tiers are offered for self-managed installations. Ask your account contact to confirm in writing which features your subscription activates, and check that the instance itself shows them. For ecosystems, list every package manager in use, commit a sample lockfile for each, and run a scan. A project with an unsupported or missing lockfile can return no findings, which looks identical to a clean result, so test with a project that contains a known vulnerable version.

Advisory data determines what a scan can find, so confirm where it comes from and how it reaches a network without internet access. On a connected instance, check how updates are fetched, how often they run, and whether outbound access must be allowed through your proxy. On an air-gapped instance, the advisory data and analyzer images must be carried across by a transfer process you own. GitLab's offline environments guide covers running its security scanners in that setting. Name the owner of the transfer, set a refresh interval you can defend, and record the date of the last import so you can show the data is current. A stale database produces no warning in the findings, so a quiet results page does not prove the data is up to date. Also confirm the Gemnasium position: the analyzer is deprecated and its removal is proposed for GitLab 20.0, which is planned for May 2027. Plan the switch before that date and treat the proposal as subject to change.

Finally, confirm how continuous rescans behave in your instance, because they keep existing projects current after an advisory is published. Run a test project with a dependency that has a published advisory, then check that the finding appears in the dependency list and vulnerability report without a new commit. Confirm which branches the scheduled scan covers, whether the default branch is included, and whether approval policy rules evaluate those results or only merge request pipelines. Ask who receives notifications and whether they route to your security queue. Also align analyzer versions with your upgrade calendar. According to the GitLab maintenance policy, patch releases ship twice a month, so an instance that lags behind may run older scanner logic. Treat each item here as something to verify in your environment, since none of them is a guarantee of behavior.

Questions buyers ask about cost, effort and running dependency scanning

Does SBOM-based dependency scanning in GitLab require Ultimate?

Yes, dependency scanning is part of the Ultimate tier, while Free and Premium do not include it. The GitLab pricing page lists application security testing and software supply chain security as Ultimate features, and Ultimate is custom priced, so the licence line is the first thing to quote. Ask the GitLab account team for a written Ultimate quote covering the exact number of users or seats, the deployment type (self-managed), and whether any add-ons apply. Confirm with the vendor which features your tier includes before you build a plan around them, because feature placement can change between releases.

How long does it take to set up dependency scanning on self-managed GitLab?

The duration depends on how much of the work is new to your organization. The main drivers are the number of projects and package ecosystems in scope, whether your GitLab instance and runners are already stable, whether the instance is online or running offline, and how many approval policies need to be designed and tested. A pilot on a few representative projects usually comes before rollout across groups. DeployOpen plans each engagement from a written scope, so the timeline is agreed in writing before work starts. Ask any partner, including DeployOpen, to break the schedule into scope confirmation, pilot, policy rollout and handover.

What does our team need to provide for a dependency scanning rollout?

The work needs a few concrete inputs from your side:

An administrator with access to the GitLab instance and group settings, so pipeline templates and policies can be applied.
Runner capacity that can execute the dependency scanning jobs alongside your existing CI load, which is planned with the GitLab Runner documentation in mind.
A pilot project with a known dependency set and a team willing to triage early findings.
Named policy owners who decide which severities block a merge request and who approves exceptions.

Agree these owners and the access model before the pilot starts, since most delays come from waiting on decisions rather than from technical work.

Can an in-house platform team set up dependency scanning without a partner?

Yes, a team with GitLab administration experience and a clear owner for security policy can usually do the core setup alone. The harder parts are often outside the template: deciding which advisories block releases, handling air-gapped instances and their advisory data, tying findings to exception workflows, and keeping the setup working through upgrades. Ask whether your team has done a GitLab upgrade through required stops and whether someone can own the policy design long term. A partner is useful when the team lacks that time or experience, and the written scope should show which parts your team keeps.

What recurring work follows after dependency scanning goes live?

Several tasks recur after go-live, and each has a cost in people's time:

Upgrades: GitLab ships monthly minor releases and patch releases, and it requires upgrades to pass through required upgrade stops, so scanner templates and policies need regression checks at each planned step.
Advisory data: in air-gapped environments, vulnerability data must be refreshed into the local mirror on a schedule your team controls.
Triage: new findings need owners, and policy exceptions need review dates.

Request a quote that states who performs each recurring task and how often, so the run cost is visible alongside the one-time build.

How do continuous rescans and advisory updates affect our workload?

Continuous rescans re-evaluate your dependency list when vulnerability advisories change, so a package that was clean last month can produce a new finding today without any code change. The workload comes from triage volume, not from the scan itself. Plan an owner for the findings queue, agree on severity thresholds for notifications, and decide which findings can wait for the next release. Confirm with GitLab how rescans are scheduled and triggered on your version and in your offline setup before promising a process to leadership.

What does a DeployOpen engagement for dependency scanning include?

DeployOpen plans, implements and documents self-hosted platforms in your own infrastructure, and most engagements are fixed-scope with deliverables and timelines agreed in writing before work starts. For this topic, a typical written scope would cover reviewing your GitLab edition and tier, configuring the dependency scanning templates on a pilot group, designing approval policies with your named owners, documenting the triage and rescan process, and handing over runbooks. Ongoing upgrades, mirror maintenance and continuous testing can be arranged as a retainer. DeployOpen does not publish prices, so request a quote based on a written scope.

How DeployOpen scopes, delivers and supports dependency scanning

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including GitLab. For SBOM-based dependency scanning, we start from the tier, scanner configuration and advisory update path your instance can actually run, then deliver the setup as a written, tested and handed-over configuration.

How we scope

Confirm your GitLab edition and that Ultimate covers dependency scanning before any build work starts.
Inventory the projects, languages and package managers that need SBOM-based dependency scanning, and which ones are excluded.
Agree in writing which pipelines, rescan schedules and approval policies are in scope, under a fixed-scope engagement.

How we build

Configure the SBOM-based dependency scanning template in CI/CD pipelines and confirm that dependency list entries are produced.
Plan continuous rescans so advisory changes reach existing projects, not only new commits, and test the schedule end to end.
For air-gapped instances, arrange the scanner and vulnerability database mirroring with your network and security teams first.

How we hand over

Document each pipeline change, rescan schedule, policy link and the owner responsible for each one.
Walk your platform, security and compliance teams through how findings flow into the dependency list and approval policies.
Deliver test evidence showing a known vulnerable dependency is detected, reported and blocked or flagged as your policy requires.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Plan re-verification of dependency scanning when you upgrade GitLab, change runners or update scanner images.
Confirm with your GitLab administrators which upgrade stop and maintenance cadence applies before scheduling scanner changes.