skip to content

In GitLab 19.4, a project still includes Jobs/Dependency-Scanning.gitlab-ci.yml. Which analyzer runs, and how do you move it to SBOM-based scanning?

level: middleimportance: nice to knowfreq 13%

answer

  1. stable template, legacy engine
  2. deprecated in 17.9, not migrated
  3. the v2 template
  4. new job name, same report file

basics

~20 s

The stable template still runs the Gemnasium-based analyzer, deprecated since GitLab 17.9 and never migrated automatically. Switch the include to Jobs/Dependency-Scanning.v2.gitlab-ci.yml, remove overrides of the gemnasium-* jobs, and point anything that referenced them at the new dependency-scanning job.

solid answer

~40 s

Dependency scanning, an Ultimate feature, is moving to the SBOM-based analyzer: it detects dependencies, writes a CycloneDX SBOM, and GitLab's built-in SBOM vulnerability scanner matches that SBOM against the GitLab advisory database. The Gemnasium-based analyzer was deprecated in GitLab 17.9 and is proposed for removal in 20.0. To avoid breaking pipelines, the stable `Jobs/Dependency-Scanning.gitlab-ci.yml` still runs it, so nothing changes until you act. To migrate, include `Jobs/Dependency-Scanning.v2.gitlab-ci.yml`, delete customizations of the `gemnasium-*` jobs, and rename references to the new `dependency-scanning` job; the `gl-dependency-scanning-report.json` artifact stays. Several Gemnasium-only CI/CD variables stop having any effect. On Self-Managed, an administrator must have Package Metadata Database sync on for your package types, or findings go missing. Scan execution policies select it with `template: v2`, the default for new policies since 19.1.

code

yaml · 7 lines
yaml
# Before: the stable template, which still runs the
# deprecated Gemnasium-based jobs
# include:
#   - template: Jobs/Dependency-Scanning.gitlab-ci.yml

include:
  - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml

go deeper

for a junior

Recall that GitLab's dependency scanning is changing engines: the old Gemnasium-based analyzer is deprecated, and the v2 template runs the SBOM-based one.

for a middle

Explain which template runs which analyzer, the job rename to dependency-scanning, the unchanged report file and the variables that stop working.

for a senior

Plan a fleet migration: inventory affected projects, check Package Metadata Database sync, update policies with template: v2, and compare finding counts so silent gaps are caught.

for a principal

Decide the migration timing against the proposed 20.0 removal, weighing the new malware matching against per-ecosystem migration effort across teams.

## Two analyzers behind one feature name GitLab **dependency scanning** finds known vulnerabilities in a project's runtime, development and transitive dependencies. It is an **Ultimate** feature, and in GitLab 19.4 two different engines can sit behind it: - The **Gemnasium-based analyzer** is the original pipeline-based design. It detects dependencies and matches them against the GitLab Advisory Database inside a CI/CD job. Its jobs are named `gemnasium-dependency_scanning`, `gemnasium-maven-dependency_scanning` and `gemnasium-python-dependency_scanning`. - The **SBOM-based analyzer** detects dependencies and their relationships, the dependency graph, and writes a **CycloneDX SBOM**, a software bill of materials. GitLab's built-in SBOM vulnerability scanner then matches that SBOM against the advisory database. It is the same scanner that continuous vulnerability scanning already used, and its job is named `dependency-scanning`. The Gemnasium-based analyzer was **deprecated in GitLab 17.9** and is proposed for removal in **GitLab 20.0**, although GitLab says the removal timeline is not final. The change is a breaking one, so GitLab does **not** migrate existing projects automatically. ## Which template runs what | Configuration | Analyzer that runs in GitLab 19.4 | |---|---| | `Jobs/Dependency-Scanning.gitlab-ci.yml` (stable) | Gemnasium-based only; kept unchanged so pipelines do not break | | `Jobs/Dependency-Scanning.latest.gitlab-ci.yml` | Gemnasium-based by default; `DS_ENFORCE_NEW_ANALYZER` opts in to the new analyzer, but only at version `v1` and without dependency resolution jobs | | `Jobs/Dependency-Scanning.v2.gitlab-ci.yml` | SBOM-based analyzer, `dependency-scanning` job | | Scan execution policy, `template: v2` | SBOM-based analyzer; `v2` is the default for new policies since 19.1 | So the project in the question, still on the stable template, is running the deprecated engine and will keep doing so. ## Migrating a project 1. **Find the projects.** The security inventory shows scanner coverage across groups. Otherwise, search for includes of the two legacy templates, for their names in policy YAML, and for the `gemnasium-*` job names. 2. **Remove overrides of the legacy jobs.** The `v2` template does not define the `gemnasium-*` jobs, so a customization that extends or overrides one of them now refers to a job that does not exist and can make the configuration invalid. 3. **Switch the include** to `Jobs/Dependency-Scanning.v2.gitlab-ci.yml`. 4. **Rename references.** Downstream jobs that consumed the legacy report must point at `dependency-scanning` instead. The report file, `gl-dependency-scanning-report.json`, keeps its name. 5. **Apply the language-specific steps** for each ecosystem in the project, then confirm that the new job produces findings. For projects covered by a **scan execution policy**, edit the policy's `dependency_scanning` action to use the `v2` template and the change reaches every project in scope. A policy that injects jobs some other way needs its own CI/CD configuration edited. ## What changes besides the include - **CI/CD variables.** Gemnasium-only variables such as `DS_EXCLUDED_ANALYZERS`, `DS_REMEDIATE`, `DS_IMAGE_SUFFIX` and `GEMNASIUM_DB_REMOTE_URL` keep working with the old analyzer but have no effect on the new one. - **Features that do not carry over.** Resolving a vulnerability automatically for Yarn projects, and dependency scanning of vendored JavaScript libraries, were deprecated with the old analyzer. - **Specialised components.** The per-ecosystem dependency scanning CI/CD components give way to the main dependency scanning component, which covers every supported package manager. - **The Package Metadata Database.** The new analyzer needs it synchronized for each package type a project uses. GitLab.com already syncs every supported type. On Self-Managed and Dedicated, an administrator configures the sync, and a package type left out of it shows up as missing findings. ## What GitLab 19.4 adds In GitLab 19.4, dependency scanning using SBOM also matches components against **GitLab malware advisories**, behind the `sbom_scan_malware_findings` feature flag, which is enabled by default. Continuous dependency scanning, which rescans the default branch's SBOM components whenever the advisory data changes, gained the same matching. Both belong to the SBOM-based path, which is one more reason to migrate. ## Pitfalls to expect - A migrated pipeline can quietly show **fewer findings** when a package type is not synchronized. Compare finding counts before and after. - For Maven, Gradle and Python projects the `v2` template adds **dependency resolution jobs** in the `.pre` stage, and by default a failed resolution job does not fail the pipeline. The `dependency-scanning` job can still succeed and upload a report, so check the resolution jobs when results look thin. - Unlike most scanner templates, the `v2` template runs its job in **merge request pipelines** by default. A project that uses only branch pipelines can end up with two pipelines per merge request; setting `AST_ENABLE_MR_PIPELINES` to `"false"` turns that off. - Do not leave a project on the `latest` template expecting the new engine: without the opt-in variable it still runs Gemnasium.

  • After a GitLab Self-Managed project switches to the v2 dependency scanning template, Maven findings disappear. What do you check?
    Whether the instance's Package Metadata Database is synchronizing Maven package data. The SBOM-based analyzer resolves advisories from that data; if a package type is not selected for sync, its components get no matches and findings go missing. An administrator fixes it in the instance's security and compliance settings.
  • A GitLab group enforces dependency scanning through a scan execution policy created before 19.1. How do you migrate it?
    Edit the policy's dependency_scanning scan action to set template: v2. Scan execution policies are built on the CI/CD templates, so the change propagates to every project in the policy's scope. Then apply the language-specific steps for the projects it covers. New policies get v2 by default since GitLab 19.1.

  • GitLab migrated every project to SBOM-based dependency scanning automatically in 17.9.
  • The Gemnasium-based analyzer was already removed in GitLab 18.
  • Switching to the v2 template renames the report file, so downstream jobs need a new path.
  • The latest dependency scanning template always runs the SBOM-based analyzer.
  • Old gemnasium-* job overrides keep working unchanged after moving to v2.

Assumes GitLab 19.4; Gemnasium-based dependency scanning was deprecated in 17.9 (removal proposed for 20.0), v2 became the default template for new scan execution policies in 19.1, and malware advisory matching arrived in 19.4.