Migrating from Gemnasium to SBOM-based dependency scanning in GitLab
Moving off the Gemnasium analyzer is a change to pipeline templates, security policies and the way reviewers read findings, not a data import, and the effort depends on how many projects and policies still reference the old jobs. For a self-managed team, the deadline is GitLab's proposed removal of the analyzer in GitLab 20.0, which GitLab plans for May 2027. Before anything changes, build an inventory: every .gitlab-ci.yml that includes the Gemnasium template, every group or instance CI/CD include that pulls it in, and every scan execution or merge request approval policy that names a job or analyzer. Treat that inventory as the work plan, because one shared template can affect many projects at once. Mark the projects that use dependency findings to block merges, since a gap in coverage there has the largest effect.
On a test branch, enable SBOM-based dependency scanning alongside the old job for a representative project and compare the outputs. Expect differences. The two approaches read dependencies differently, so the same project can show different packages, versions and severities. Decide in advance how to handle them: which findings are new, which earlier findings were suppressed or dismissed, and whether vulnerability states need to be re-triaged in the vulnerability report. Then update each policy to reference the new job name and remove the old one, and confirm that approval rules still trigger on the same classes of finding. Roll the change through a staging group before altering the shared template, and keep the old include available until the comparison is signed off.
SBOM-based dependency scanning belongs to the paid tier that includes application security testing and software supply chain security. GitLab's pricing page lists that tier as custom priced, so confirm entitlement and request a quote before you commit the rollout schedule. Also confirm the current analyzer and template names, the removal status and any version-specific behavior in GitLab's documentation for your instance version, because the 20.0 date is a proposal and names can change between releases. Finally, schedule the template change inside your normal upgrade cycle. Required upgrade stops still apply, so the migration should not become the reason your instance falls behind on supported versions.
What maps cleanly from Gemnasium and what does not
This table compares what your current Gemnasium setup relies on with its SBOM-based dependency scanning equivalent, and marks each item as direct, partial or needing a decision. Read the Mapping column first, because anything marked partial or needing a decision must be checked in your own pipelines before cutover. Findings from the two methods may not match one for one, so historical records and policy rules need verification rather than assumption. Confirm each mapping against the current GitLab dependency scanning documentation before you rely on it.
| Capability | Gemnasium today | SBOM-based dependency scanning | Mapping |
|---|---|---|---|
| Dependency findings in the security dashboard | Findings produced by the Gemnasium job appear as dependency vulnerabilities | Findings appear through the dependency list and vulnerability reporting fed by the SBOM job | Partial: finding sets may differ |
| Merge request security widget | Shows Gemnasium results on the merge request | Shows results from the new dependency scanning report once the job runs | Direct in purpose: confirm widget output on your branches |
| Job names in .gitlab-ci.yml | Gemnasium template jobs included and sometimes overridden by name | A different template with different job names and variables | Needs a decision: rename, replace or keep overrides |
| Policy rules keyed on scanner jobs | Approval rules that reference the Gemnasium job or its report | Rules must reference the new scanner and report type | Needs a decision: audit every policy project and group |
| Existing vulnerability records | Historical findings carry Gemnasium as their origin | New findings are created by the new method; old records stay as recorded | Partial: confirm how history is shown and kept |
| Method used to detect dependencies | Detects dependencies from the project's lock and manifest files | Detects dependencies from a generated SBOM of the build | Needs a decision: run both in parallel and compare |
| Offline and air-gapped instances | Analyzer and advisory data mirrored for offline use under existing guidance | Confirm the analyzer images and advisory data mirror path for this method | Needs a decision: confirm before any cutover |
Documented paths for the switch and for the evidence
These are the mechanisms your team uses to make the switch and to keep evidence of it. Each covers a different part of the change: the pipeline job, the policies that enforce it, the findings, the dependency inventory and the release window. Confirm what each one provides in your GitLab version before you write the migration plan.
CI/CD templates that enable scanning
Dependency scanning runs as a pipeline job that you include from GitLab's CI/CD templates, so the switch starts with the include line and the job names it creates. Check which template and analyzer job your version uses for SBOM-based scanning, then search every .gitlab-ci.yml file and shared template in your groups for references to the Gemnasium job. Remove the old job only after the replacement job passes on your default branch.
Policy project and scan execution
Scan execution policies in the security policy project can require a scanner to run across groups and projects. A policy written against the old job will keep pointing at a job that no longer runs, so inventory every policy that names the Gemnasium job before the switch. Update each one to the replacement, test it in a non-enforcing project first, and confirm that the policy editor in your version accepts the new scanner.
Vulnerability management views and exports
The vulnerability report lets you filter findings by scanner, state and severity, and it is where analysts triage, dismiss or confirm findings during a parallel run. Compare the same projects before and after the switch and record each difference, noting whether advisory data or the analyzer explains it. Confirm which export formats your version offers and whether exports include the scanner name, so you can separate findings from the two sources.
Dependency list and SBOM export
The dependency list is the inventory that SBOM export draws from, so the switch changes what your CycloneDX output contains. Dependency scanning has to run on the default branch before the list is complete, and an SBOM produced before the switch will not match one produced after it. Confirm which SBOM formats and fields your version supports, and keep a dated export from the old analyzer as evidence of the prior state.
Keeping historical findings
Migrating scanner results is not an import feature in GitLab, so older Gemnasium findings do not move into the new scanner's records automatically. Choose one of three paths and document it: keep the existing vulnerability history in place, export findings to your own evidence store before the switch, or accept a dated retention decision with a named owner. Decide retention before the switch, and ask your security lead which path your auditors expect.
Release timing and support windows
The Gemnasium removal is proposed for GitLab 20.0, which the maintenance policy plans for May 2027, so the switch does not need to follow a deadline set by a patch release. Bug fixes are backported only to the current stable release, while security fixes also reach the previous two monthly releases, so plan the change inside a supported window. Confirm the removal timing in the current deprecation notice before you schedule the work.
The sequence: inventory, pilot, parallel run, cutover and decommission
This sequence moves every project off the Gemnasium analyzer without a gap in dependency coverage, and it leaves a recorded trail for auditors. Each phase has an owner and a check that must pass before the next one starts.
Inventory every reference to Gemnasium
Search every project, shared template repository and security policy project for includes and jobs that call the Gemnasium analyzer, and list each one with its group, owner and pipeline. Include policies that match on the old job names, since these break silently when the job disappears. Map your upgrade calendar at the same time. The current maintained releases are 19.5, 19.4 and 19.3, and required upgrade stops fall at versions such as 19.5 and 19.8, so align the cutover window with the upgrade you plan to run. The step is done when you have one inventory that every later phase uses.
Pilot SBOM-based dependency scanning on a few projects
Choose a small set of projects that cover different languages and package managers, then enable the SBOM-based dependency scanning template on a branch in each. Before you start, confirm with your GitLab account team or the GitLab documentation that your license tier includes this scanner, because the pilot will fail or return no results without it. Check that the job runs on your self-managed runners and, if your instance is offline, that the analyzer images and vulnerability data are mirrored. The step is done when each pilot project produces a dependency list and a report artifact without errors.
Run both scanners in parallel
Keep the Gemnasium job and the SBOM-based job running side by side on the same pipelines for a set period agreed by the security and platform teams. Both results should appear in the merge request and the vulnerability report without changing any approval rules yet, so that no team is blocked by the trial. Record any job failures, timeouts or runner capacity issues as they occur. The step is done when the agreed period has passed and every project in scope has produced results from both scanners on its default branch.
Compare findings by project, severity and dependency
Export the findings from both scanners for each project and line them up by project, severity and dependency name and version. Sort the differences into three groups: vulnerabilities found by both, findings only the old analyzer reported, and findings only the SBOM-based scanner reported. Ask the security team to triage the second and third groups, because a difference can mean a false positive, a dependency the old analyzer could not read, or a real gap. Document the reasons for each accepted difference. The step is done when every difference has a recorded decision and the security owner has signed off the comparison.
Cut over templates and policies group by group
Move one group at a time by updating the shared template includes and replacing references to the old job names in security policies, starting with the groups that have the fewest dependencies on other teams. Tell each group's approvers and project maintainers before the change lands, including what the new job is called and which findings will look different. Watch the first few merge requests after each switch for failed approval rules or missing reports. The step is done when each group's pipelines run the new scanner and its policies evaluate against the new results.
Remove the old job and its references
Once every group runs the SBOM-based scanner, delete the Gemnasium includes, job definitions and any leftover variables from templates, projects and policy files. Search the instance again with the inventory from the first step to confirm that nothing still calls the old analyzer. Keep the old reports available according to your retention settings so that historical findings remain traceable. GitLab has proposed removing the Gemnasium analyzer in GitLab 20.0, which is planned for May 2027, so finish before that release reaches your environment. The step is done when the search returns no matches and a test pipeline in each group passes.
Record the change for audit
Write a change record that lists the inventory, the pilot results, the comparison decisions, the cutover dates per group and the removal commit or merge request for each template and policy. Store it in the same system that holds your other change management evidence, and link it to the relevant change tickets. Confirm with your auditor or compliance lead which evidence format they expect, since requirements differ by framework and organization. The step is done when the record is complete, reviewed by the security owner and filed where auditors can find it.
Updating policies that still point at old jobs
Policies are the highest-risk part of this move because they fail quietly. An approval rule or scan execution policy that names a Gemnasium job keeps evaluating until that job is renamed or removed, and then it can stop enforcing without raising an error that anyone sees in a merge request. Before you change any template, build an inventory of every policy that refers to the Gemnasium job names, the analyzer image or the related scanner settings. Treat that inventory as a migration deliverable, with an owner for each entry.
Start the search in the security policy project, since group-level and project-level policies are typically linked from there, then check group and project security settings for linked policy configurations and for CI/CD variables that override scanner behavior. Search pipeline configuration in the projects that are in scope as well, because a policy that enforces a job by name only works if the job exists in the pipeline it runs against. Confirm the exact policy schema, job matching fields and how links are inherited in the GitLab documentation for your target version, since these details change between releases and this page does not set them out.
Test each changed policy on a pilot group before it reaches the wider estate. Choose a group whose projects already run the new SBOM-based job, link the updated policy only to that group, and open a merge request that should be blocked and one that should pass. Keep the Gemnasium-based policy active during the parallel run only where its scope is clearly separate from the pilot. Avoid linking two policies that both require the same scanner to the same project, because overlapping requirements make the outcome of a merge request hard to predict and hard to explain to an auditor. Retire the old link only after the pilot results match what you expected.
Online and offline instances need different preparation
On an instance that reaches GitLab's advisory sources directly, the work centers on the pipeline and the policies that reference the old job. Changes land in project configuration and in group-level settings, and the analyzer's advisory data updates without a transfer step.
- Template include: Replace the Gemnasium-based template include in
.gitlab-ci.ymlwith the SBOM-based dependency scanning template, and check every project that inherits the old include through a shared template or CI/CD component. - Policy references: Search your security policy project and merge request approval policies for references to the old analyzer job names, since those rules can stop matching once the job disappears.
- Parallel run: Keep both jobs running on a non-production branch for a few pipelines so you can compare output before removing the old job.
- Dependency list and vulnerability records: Confirm how the new analyzer populates the dependency list, and decide how you will handle any finding that appears only under the old scanner.
- Rescan cadence: Confirm which pipeline or schedule runs the scan so advisory changes are picked up on a regular basis.
Before you change the default template for the whole group, check that a test merge request triggers the expected policy and that the new job appears in the pipeline graph.
On an air-gapped instance, the template change is the simple part. The analyzer images, the vulnerability data and any package sources the analyzer reads must be brought in from outside the network before the new job can run. GitLab documents running security scanners offline separately, so use that guidance for the procedure and treat this tab as the checklist of decisions to make first: GitLab offline environments.
- Mirror the analyzer images: Pull the analyzer images in a connected environment, transfer them through your approved media process, and push them to your internal container registry under the paths the template expects.
- Vulnerability data: Agree how advisory data reaches the instance, including the transfer cadence and who approves each import. Stale data can weaken the evidence you give an auditor.
- Cloud licensing opt-out: Confirm the instance is configured to skip the cloud licensing check before cutover, and record the setting in your change record.
- Package sources: Identify which language package sources the scanner reads and point them at internal mirrors where needed.
- Test against the mirror: Run the updated templates on a sample of projects for each language your teams build, and compare results with the baseline from your last export.
Confirm that a scan completes without outbound network access and that the mirror refresh has a named owner before you retire the old job.
Whichever environment you run, the cutover decision rests on the same comparison. The two analyzers can report different sets of findings, so agree on what counts as a regression before the comparison begins, and record the agreed criteria in the change request.
- Agree the baseline: Export findings from the old job for a recent default-branch pipeline and store them next to the new job's output for the same commit.
- Classify differences: Sort each difference into a new finding, a dropped finding or a changed severity or version, and assign an owner to each group.
- Update policies: Point approval rules and policy project references at the new job name, then test one merge request for each policy scope.
- Set the removal date: Schedule removal of the old template to fit your change calendar. GitLab's maintenance policy places the planned GitLab 20.0 release in May 2027, and the old analyzer's proposed removal is tied to that release.
- Document the decision: Keep the comparison results, policy changes and approvals in your change management system so the evidence travels with the release.
Confirm that no group or project still references the old template before you close the migration ticket.
What drives the effort and duration of the move
This table lists the factors that change how much work the Gemnasium to SBOM-based dependency scanning move takes, whether each cost is one-time or recurring, and what to ask for in a written scope. Use it to see which drivers apply to your instance before comparing quotes. The main takeaway is that project count, policy coupling and offline constraints usually matter more than the template swap itself.
| Driver | Why it changes effort | One-time or recurring | What lowers it, and what to ask for in scope |
|---|---|---|---|
| Projects and groups with custom includes | Each project or group that includes the Gemnasium template directly or through a custom CI file needs its include and job names checked and changed. | One-time | Lower with shared templates in a central project. Ask the scope to list every project and group, and which of them override the scanner jobs. |
| Policies and approval rules tied to scanner jobs | Policies that match on old job names or analyzer output must be found, rewritten and tested so enforcement does not silently lapse. | One-time, with ongoing review when rules change | Lower by consolidating rules into fewer policy projects. Ask the scope to inventory each policy, its scope and the job or report it references. |
| Online or offline instance | Offline instances need the new analyzer images and advisory data mirrored and tested before any template change. GitLab documents separate guidance for running its security scanners offline. | One-time for setup, recurring for mirror refreshes | Lower by mirroring analyzers on a fixed schedule before the cutover. Ask whether the scope includes the mirror pipeline and who maintains it. |
| Historical vulnerability data to preserve | Teams that need older findings for audit or trend reporting must decide how to retain, export or annotate them, since results from the two analyzers will not match one for one. | One-time for export and archive, recurring for storage | Lower by setting a retention window agreed with compliance. Ask the scope to state what export format is delivered and who signs off on the archive. |
| Approvers who must learn the new findings | Security and development approvers must recognize the new dependency list, severities and license data before they can approve merge requests confidently. | One-time training, recurring for new joiners | Lower with a short written guide and a pilot group. Ask the scope to name the approver groups, number of sessions and the materials to be delivered. |
| Upgrade timing | If the move coincides with a GitLab upgrade, upgrade stops and the release on which the analyzer change lands must be checked, which adds testing. GitLab 20.0 is planned for May 2027 according to the maintenance policy. | One-time | Lower by completing the move on a current stable release well before the proposed removal. Ask the scope which GitLab version is the baseline and whether upgrades are included. |
| Change control and evidence requirements | Many organizations require a change request, test evidence and rollback plan for each pipeline or policy change, which adds documentation and approval cycles. | One-time for the first change, recurring for each later change | Lower by batching changes into a few approved windows. Ask the scope for the deliverables, such as test records and a rollback procedure, and who approves each step. |
| Ultimate licensing | SBOM-based dependency scanning and the policies that enforce it are part of Ultimate, which is custom priced. Licensing is a separate line from implementation work. | Recurring, per the agreement with GitLab | Confirm your current tier before scoping. Ask GitLab for a quote, and ask DeployOpen to show the licensing assumptions in the written scope. |
What usually goes wrong and how to prevent it
The risks below cluster around three moments: the inventory of jobs and policies, the parallel run and the cutover itself. Each card names the failure, the phase where it starts and the check that prevents it. Work through them in order, because several depend on evidence gathered in earlier phases.
Policies stop enforcing silently
Approval policies and pipeline rules that reference Gemnasium job names can stop matching once the template changes to the SBOM-based dependency scanning job. GitLab may not report this as an error, so the merge request simply looks compliant. During the inventory phase, list every policy and rule that names a gemnasium job, update the references, and then open a test merge request to confirm the required scanner still runs and appears in the approval check.
Analyzers report different findings
The two analyzers do not share a vulnerability database, dependency detection method or version matching, so approvers may see new findings that were never reported before, or old ones that disappear. Without warning, a team can read this as a regression in its code. Run both analyzers on the same default branch during the parallel phase, export the results, and classify each difference as a detection gap, a database difference or a real change before approvers rely on the new report.
Removal deadline before cutover
Gemnasium is deprecated and its removal is proposed for GitLab 20.0, which GitLab plans for May 2027. Teams that schedule cutover late in that window have little room to fix policies, mirror images and train approvers. Put the removal date in the migration plan, confirm the current status with the GitLab maintenance policy and the release notes, and set an internal cutover date that leaves time for the parallel run and one rollback.
Stale offline mirror at scan time
On an air-gapped instance, the SBOM-based analyzer image and its advisory data come from a mirror that someone must refresh. If the mirror predates the parallel run, the new analyzer may run against old advisories and produce results that differ from the connected environment for reasons unrelated to the analyzer itself. Before starting the parallel run, confirm the mirror holds the analyzer image version you plan to pin, record the refresh date, and repeat the check before cutover using the guidance in the offline environments documentation.
Parallel run treated as optional
Teams under delivery pressure often switch the template directly, then discover missing or new findings after a release is blocked. The parallel run exists to surface those differences while both analyzers can still be compared. Make the comparison a named gate in the plan, assign an owner from security and one from engineering, and require a written sign-off that lists each accepted difference before the old template is removed from the pipeline configuration.
Lost audit evidence from old scans
Gemnasium reports, dependency lists and approval records are often the evidence that a release was checked at a given time. Once the pipeline stops producing them, older results can be hard to find, and an auditor may ask for proof of the scanner in use on a past date. Before cutover, export the final Gemnasium reports and the dependency list for each in-scope project, store them with the other change records, and confirm that your backup and retention settings keep them for as long as your policy requires.
Questions buyers ask before moving from Gemnasium
How much does moving off Gemnasium cost?
The cost depends on the written scope, not on the analyzer itself. The main components are the people doing the work (inventory, template changes, policy rewrites, validation and cutover) and the GitLab subscription that includes dependency scanning, which the GitLab pricing page places in its top tier with custom pricing. Migration labor is one-time, while licensing recurs per user or per contract term. Costs rise with the number of projects, the number of CI templates that include the old analyzer, custom job overrides, and the number of approval policies that name the old jobs. Ask any quote to itemize the inventory, the migration work, validation, and any retainer for later rescans or upgrades, and to state what is excluded.
How long will the move take, and what sets the timeline?
The timeline follows the scope, so no general duration applies. A small group with a few projects and standard templates moves on a very different schedule from an organization with hundreds of projects, custom includes, and policies enforced across groups. The main drivers are the number of projects and pipelines, how many use the Gemnasium template or overrides, how many policies reference the old job names, how long reviewers take to approve changes, and how many change windows exist for production pipelines. Run the findings comparison in parallel with cutover so coverage is confirmed before the old job is removed. Ask for a milestone schedule in the written scope that names the dependencies and the approver for each step.
What must our team provide before the engagement starts?
Most delays in a migration like this come from access and decisions, so have these ready before work begins:
- Read access to the groups, projects and CI configuration that include the Gemnasium template
- Admin access to the GitLab instance, including the security policy project and group-level settings
- Named approvers for template changes and policy edits, with the review time they can commit
- Change windows for production pipelines and a named owner for rollback decisions
Confirm the GitLab tier on every instance in scope, because the GitLab pricing page lists security features by tier and dependency scanning depends on the tier you hold.
Can our own platform team do this without a partner?
Yes, if the team has the skills and the time. The work needs people who can write and review GitLab CI/CD configuration, including includes, rules and job overrides; administer a self-managed instance and its security policy project; understand which package ecosystems your dependency list covers; and check scanner output against known vulnerabilities. The gap is usually validation: confirming that the new analyzer covers what the old one reported, and documenting that result for auditors. Internal teams often underestimate how many projects inherit templates from shared groups. An implementation partner plans, implements and documents a fixed-scope change inside your infrastructure and hands over the configuration and the evidence. Decide based on skills, capacity and deadline, and ask for a scope that states what your team owns after handover.
What happens if the migration slips past GitLab 20.0?
The Gemnasium removal is proposed for GitLab 20.0, which the GitLab maintenance policy lists as planned for May 2027. If your pipelines still reference the old job when that release arrives, dependency results stop and pipelines that depend on them can fail, so check the deprecation notice in the release notes for each version you run. Your instance must also pass through required upgrade stops, so the move to 20.0 needs its own upgrade path. Bug fixes are backported only to the current stable release, while security fixes reach the previous two monthly releases, so staying on an older line narrows the fixes you receive. Finish the migration before your upgrade window and list the upgrade stops in the same schedule.
Do historical Gemnasium findings carry over to SBOM-based results?
Do not assume they will. Findings are tied to the analyzer and job that produced them, and a different analyzer can match dependencies, versions and advisories differently, so old vulnerability records will not automatically line up with new results. Before cutover, export the existing reports and vulnerability records as evidence, run both analyzers on the same default branch, and compare the two lists by package, version and identifier. Record each difference as a confirmed gap, a false positive or an expected change in scope, with a named owner for each decision. Confirm with the current GitLab documentation for your version how existing vulnerabilities appear after the change, because that behavior decides whether you keep past triage or re-triage.
Does an offline or air-gapped instance change the migration?
Yes, it adds mirroring work before any template change. GitLab documents running security scanners in offline environments, so the analyzer images, the advisory data used for matching and any package sources the scan needs must be available inside your network before the new job runs. Check which images and data the SBOM-based analyzer needs for your version, and mirror them through your approved process. Test on a staging instance with the same restrictions, because a job that works online can fail when a data source is blocked. Include the mirror refresh schedule in the written scope, since the data changes over time and someone must own that work after the engagement ends.
How DeployOpen scopes and delivers the move
DeployOpen treats the move off Gemnasium as a scoped change to your GitLab pipelines and policies, not a one-line template swap. We inventory the jobs and policies that reference the old analyzer, agree the target state in writing, and deliver it in your own infrastructure with evidence your reviewers can check.
How we scope
- Inventory every pipeline, included template and policy that references the Gemnasium analyzer job in your instance
- Confirm which GitLab tier and features your organization holds before agreeing which dependency scanning results you can rely on
- Write the scope, deliverables and timeline into a fixed-scope agreement before any pipeline changes start
- Agree how baseline findings will be compared and who signs off on accepted differences
How we build
- Switch affected projects to the SBOM-based dependency scanning template in a test group before any production change
- Run old and new scanners side by side on representative projects and record where findings differ and why
- Update scan execution and merge request approval policies so they reference the new jobs and report names
- Confirm offline or air-gapped scanner sources and advisory data are mirrored if your instance runs without internet access
How we hand over
- Deliver a written record of changed templates, policy references, comparison results and accepted differences
- Document the rollback path and the steps to repeat the change on additional groups or instances
- Walk your platform and security teams through the new results, the dependency list and the approval workflow
- Hand over configuration as code so future changes go through your normal review process
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Agree in advance how we will track GitLab upgrade stops and deprecation notices that affect scanner jobs
- Ask us to review new scanner releases and policy changes against your written baseline before they reach production
- Scope retainer hours, response expectations and review cadence in writing with your quote
