Migrating to Dependency Scanning using SBOM

The Dependency Scanning feature is upgrading to the GitLab SBOM Vulnerability Scanner. As part of this change, the Dependency Scanning using SBOM feature and the new Dependency Scanning analyzer replace the legacy Dependency Scanning feature based on the Gemnasium analyzer. However, due to the significant changes this transition introduces, it is not implemented automatically and this document serves as a migration guide.

Follow this migration guide if you use GitLab Dependency Scanning and any of the following conditions apply:

• The Dependency Scanning CI/CD jobs are configured by including a Dependency Scanning CI/CD templates.

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

• The Dependency Scanning CI/CD jobs are configured by using Scan Execution Policies.

• The Dependency Scanning CI/CD jobs are configured by using Pipeline Execution Policies.

Understand the changes

Before you migrate your project to Dependency Scanning using SBOM, you should understand the fundamental changes being introduced. The transition represents both a technical evolution and a new approach to how Dependency Scanning works in GitLab.

A new approach to security scanning

When using the legacy Dependency Scanning feature, all scanning work happens within your CI/CD pipeline. When running a scan, the Gemnasium analyzer handles two critical tasks simultaneously: it identifies your project’s dependencies and immediately performs a security analysis of those dependencies, all within the same CI/CD job.

The Dependency Scanning using SBOM approach separates these tasks into two distinct phases:

• First, when you run the new Dependency Scanning analyzer in the CI/CD pipeline, it focuses solely on creating a comprehensive inventory of your project’s dependencies. This inventory is captured in a CycloneDX SBOM (Software Bill of Materials) report.
• Second, after the CI/CD pipeline completes, the GitLab platform processes your SBOM report and performs a thorough security analysis using the built-in GitLab SBOM Vulnerability Scanner. You’re already benefiting from this scanner with the Continuous Vulnerability Scanning feature.

This separation of concerns brings several advantages for future enhancements, but it also means some changes in how you work with the scan results. For instance, since the security analysis happens outside the CI/CD pipeline, certain workflows are no longer compatible. This also impacts the availability of some functionalities that depend on the security analysis to run in the CI/CD pipeline. Please review the deprecation announcement for a complete description.

CI/CD configuration

To prevent disruption to your CI/CD pipelines, the new approach is not yet applied to the stable Dependency Scanning CI/CD template (Dependency-Scanning.gitlab-ci.yml) and you must use the latest template (Dependency-Scanning.latest.gitlab-ci.yml) to enable it. Other migration paths might be considered as the feature gains maturity.

The latest Dependency Scanning CI/CD template (Dependency-Scanning.latest.gitlab-ci.yml) still maintains backward compatibility by default. It continues to run existing Gemnasium analyzer jobs, while the new Dependency Scanning analyzer only activates for newly supported languages and package managers. You can opt-in to use the new Dependency Scanning analyzer for all projects by configuring the DS_ENFORCE_NEW_ANALYZER CI/CD variable to true.

If you’re using Scan Execution Policies, these changes apply in the same way because they build upon the CI/CD templates.

If you’re using the main Dependency Scanning CI/CD component you won’t see any changes as it already employs the new analyzer. However, if you’re using the specialized components for Android, Rust, Swift, or Cocoapods, you’ll need to migrate to the main component that now covers all supported languages and package managers.

Build support for Java and Python

One significant change affects how dependencies are discovered, particularly for Java and Python projects. The new analyzer takes a different approach: instead of attempting to build your application to determine dependencies, it requires explicit dependency information through lockfiles or dependency graph files. This change means you’ll need to ensure these files are available, either by committing them to your repository or generating them dynamically during the CI/CD pipeline. While this requires some initial setup, it provides more reliable and consistent results across different environments. The following sections will guide you through the specific steps needed to adapt your projects to this new approach if that’s necessary.

Accessing scan results

When you migrate to Dependency Scanning using SBOM, you’ll notice a fundamental change in how security scan results are handled. The new approach moves the security analysis out of the CI/CD pipeline and into the GitLab platform, which changes how you access and work with the results. With the legacy Dependency Scanning feature, CI/CD jobs using the Gemnasium analyzer generate a Dependency Scanning report artifact containing the scan results, and upload it to the platform. You can access these results by all possible ways offered to job artifacts. This means you can process or modify the results within your CI/CD pipeline before they reach the GitLab platform. The Dependency Scanning using SBOM approach works differently. Since the security analysis now happens within the GitLab platform using the built-in GitLab SBOM Vulnerability Scanner, you won’t find the scan results in your job artifacts anymore. Instead, GitLab analyzes the CycloneDX SBOM report artifact that your CI/CD pipeline generates, creating security findings directly in the GitLab platform. To help you transition smoothly, GitLab maintains some backward compatibility. While using the Gemnasium analyzer, you’ll still get a standard artifact (using artifacts:paths) that contains the scan results. This means if you have succeeding CI/CD jobs that need these results, they can still access them. However, keep in mind that as the GitLab SBOM Vulnerability Scanner evolves and improves, these artifact-based results won’t reflect the latest enhancements. When you’re ready to fully migrate to the new Dependency Scanning analyzer, you’ll need to adjust how you programmatically access scan results. Instead of reading job artifacts, you’ll use GitLab GraphQL API, specifically the (Pipeline.securityReportFindings resource).

Identify affected projects

Understanding which of your projects need attention for this migration is an important first step. The most significant impact will be on your Java and Python projects, since the way these handle dependencies is changing fundamentally. To help you identify affected projects, GitLab provides the Dependency Scanning Build Support Detection Helper tool. This tool examines your GitLab group or self-managed instance and identifies projects that currently use the Dependency Scanning feature with either the gemnasium-maven-dependency_scanning or gemnasium-python-dependency_scanning CI/CD jobs. When you run this tool, it creates a comprehensive report of projects that will need your attention during the migration. Having this information early helps you plan your migration strategy effectively, especially if you manage multiple projects across your organization.

Migrate to Dependency Scanning using SBOM

To migrate to the Dependency Scanning using SBOM method, perform the following steps for each project:

1. Remove existing customization for Dependency Scanning based on the Gemnasium analyzer.
   • If you have manually overridden the gemnasium-dependency_scanning, gemnasium-maven-dependency_scanning, or gemnasium-python-dependency_scanning CI/CD jobs to customize them in a project’s .gitlab-ci.yml or in the CI/CD configuration for a Pipeline Execution Policy, remove them.
   • If you have configured any of the impacted CI/CD variables, adjust your configuration accordingly.
2. Enable the Dependency Scanning using SBOM feature with one of the following options:
   • Use the latest Dependency Scanning CI/CD template Dependency-Scanning.latest.gitlab-ci.yml to run the new Dependency Scanning analyzer:
     1. Ensure your .gitlab-ci.yml CI/CD configuration includes the latest Dependency Scanning CI/CD template.
     2. Add the CI/CD variable DS_ENFORCE_NEW_ANALYZER and set it to true. This variable can be set in many different places, while observing the CI/CD variable precedence.
     3. Adjust your project and your CI/CD configuration if needed by following the language-specific instructions below.
   • Use the Scan Execution Policies to run the new Dependency Scanning analyzer:
     1. Edit the configured scan execution policy for Dependency Scanning and ensure it uses the latest template.
     2. Add the CI/CD variable DS_ENFORCE_NEW_ANALYZER and set it to true. This variable can be set in many different places, while observing the CI/CD variable precedence.
     3. Adjust your project and your CI/CD configuration if needed by following the language-specific instructions below.
   • Use the Dependency Scanning CI/CD component to run the new Dependency Scanning analyzer:
     1. Replace the Dependency Scanning CI/CD template’s include statement with the Dependency Scanning CI/CD component in your .gitlab-ci.yml CI/CD configuration.
     2. Adjust your project and your CI/CD configuration if needed by following the language-specific instructions below.
   • Use your own CycloneDX SBOM document:
     1. Remove the Dependency Scanning CI/CD template’s include statement from your .gitlab-ci.yml CI/CD configuration.
     2. Ensure a compatible SBOM document is generated by a CI/CD job and uploaded as a CycloneDX SBOM report artifact.
3. Adjust any workflow depending on the dependency_scanning report artifacts which are no longer uploaded.

For multi-language projects, complete all relevant language-specific migration steps.

Language-specific instructions

As you migrate to the new Dependency Scanning analyzer, you’ll need to make specific adjustments based on your project’s programming languages and package managers. These instructions apply whenever you use the new Dependency Scanning analyzer, regardless of how you’ve configured it to run - whether through CI/CD templates, Scan Execution Policies, or the Dependency Scanning CI/CD component. In the following sections, you’ll find detailed instructions for each supported language and package manager. For each one, we’ll explain:

• How dependency detection is changing
• What specific files you need to provide
• How to generate these files if they’re not already part of your workflow

Bundler

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Bundler projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the Gemfile.lock file (gems.locked alternate filename is also supported). The combination of supported versions of Bundler and the Gemfile.lock file are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the Gemfile.lock file (gems.locked alternate filename is also supported) and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a Bundler project

Migrate a Bundler project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps needed to migrate a Bundler project to use the Dependency Scanning analyzer.

CocoaPods

Previous behavior: Dependency Scanning based on the Gemnasium analyzer does not support CocoaPods projects when using the CI/CD templates or the Scan Execution Policies. Support for CocoaPods is only available on the experimental Cocoapods CI/CD component.

New behavior: The new Dependency Scanning analyzer extracts the project dependencies by parsing the Podfile.lock file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a CocoaPods project

Migrate a CocoaPods project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a CocoaPods project to use the Dependency Scanning analyzer.

Composer

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Composer projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the composer.lock file. The combination of supported versions of Composer and the composer.lock file are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the composer.lock file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a Composer project

Migrate a Composer project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a Composer project to use the Dependency Scanning analyzer.

Conan

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Conan projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the conan.lock file. The combination of supported versions of Conan and the conan.lock file are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the conan.lock file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a Conan project

Migrate a Conan project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a Conan project to use the Dependency Scanning analyzer.

Go

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Go projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by using the go.mod and go.sum file. This analyzer attempts to execute the go list command to increase the accuracy of the detected dependencies, which requires a functional Go environment. In case of failure, it falls back to parsing the go.sum file. The combination of supported versions of Go, the go.mod, and the go.sum files are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer does not attempt to execute the go list command in the project to extract the dependencies and it no longer falls back to parsing the go.sum file. Instead, the project must provide at least a go.mod file and ideally a go.graph file generated with the go mod graph command from the Go Toolchains. The go.graph file is required to increase the accuracy of the detected components and to generate the dependency graph to enable features like the dependency path. These files are processed by the dependency-scanning CI/CD job to generate a CycloneDX SBOM report artifact. This approach does not require GitLab to support specific versions of Go.

Migrate a Go project

Migrate a Go project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

To migrate a Go project:

• Ensure that your project provides a go.mod and a go.graph files. Configure the go mod graph command from the Go Toolchains in a preceding CI/CD job (for example, build) to dynamically generate the dependencies.lock file and export it as an artifact prior to running the Dependency Scanning job.

See the enablement instructions for Go for more details and examples.

Gradle

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Gradle projects using the gemnasium-maven-dependency_scanning CI/CD job to extract the project dependencies by building the application from the build.gradle and build.gradle.kts files. The combinations of supported versions for Java, Kotlin, and Gradle are complex, as detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer does not build the project to extract the dependencies. Instead, the project must provide a dependencies.lock file generated with the Gradle Dependency Lock Plugin. This file is processed by the dependency-scanning CI/CD job to generate a CycloneDX SBOM report artifact. This approach does not require GitLab to support specific versions of Java, Kotlin, and Gradle.

Migrate a Gradle project

Migrate a Gradle project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

To migrate a Gradle project:

• Ensure that your project provides a dependencies.lock file. Configure the Gradle Dependency Lock Plugin in your project and either:
  • Permanently integrate the plugin into your development workflow. This means committing the dependencies.lock file into your repository and updating it as you’re making changes to your project dependencies.
  • Use the command in a preceding CI/CD job (for example, build) to dynamically generate the dependencies.lock file and export it as an artifact prior to running the Dependency Scanning job.

See the enablement instructions for Gradle for more details and examples.

Maven

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Maven projects using the gemnasium-maven-dependency_scanning CI/CD job to extract the project dependencies by building the application from the pom.xml file. The combinations of supported versions for Java, Kotlin, and Maven are complex, as detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer does not build the project to extract the dependencies. Instead, the project must provide a maven.graph.json file generated with the maven dependency plugin. This file is processed by the dependency-scanning CI/CD job to generate a CycloneDX SBOM report artifact. This approach does not require GitLab to support specific versions of Java, Kotlin, and Maven.

Migrate a Maven project

Migrate a Maven project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

To migrate a Maven project:

• Ensure that your project provides a maven.graph.json file. Configure the maven dependency plugin in a preceding CI/CD job (e.g. build) to dynamically generate the maven.graph.json file and export it as an artifact prior to running the Dependency Scanning job.

See the enablement instructions for Maven for more details and examples.

npm

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports npm projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the package-lock.json or npm-shrinkwrap.json.lock files. The combination of supported versions of npm and the package-lock.json or npm-shrinkwrap.json.lock files are detailed in the Dependency Scanning (Gemnasium-based) documentation. This analyzer may scan JavaScript files vendored in a npm project using the Retire.JS scanner.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the package-lock.json or npm-shrinkwrap.json.lock files and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job. This analyzer does not scan vendored JavaScript files. Support for a replacement feature is proposed in epic 7186.

Migrate an npm project

Migrate an npm project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate an npm project to use the Dependency Scanning analyzer.

NuGet

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports NuGet projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the packages.lock.json file. The combination of supported versions of NuGet and the packages.lock.json file are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the packages.lock.json file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a NuGet project

Migrate a NuGet project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a NuGet project to use the Dependency Scanning analyzer.

pip

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports pip projects using the gemnasium-python-dependency_scanning CI/CD job to extract the project dependencies by building the application from the requirements.txt file (requirements.pip and requires.txt alternate filenames are also supported). The PIP_REQUIREMENTS_FILE environment variable can also be used to specify a custom filename. The combinations of supported versions for Python and pip are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer does not build the project to extract the dependencies. Instead, the project must provide a requirements.txt lockfile generated by the pip-compile command line tool. This file is processed by the dependency-scanning CI/CD job to generate a CycloneDX SBOM report artifact. This approach does not require GitLab to support specific versions of Python and pip. The DS_PIPCOMPILE_REQUIREMENTS_FILE_NAME_PATTERN environment variable can also be used to specify custom filnames for pip-compile lockfiles.

Alternatively, the project can provide a pipdeptree.json file generated with the pipdeptree command line utility.

Migrate a pip project

Migrate a pip project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

To migrate a pip project:

• Ensure that your project provides a requirements.txt lockfile. Configure the pip-compile command line tool in your project and either:
  • Permanently integrate the command line tool into your development workflow. This means committing the requirements.txt file into your repository and updating it as you’re making changes to your project dependencies.
  • Use the command line tool in a preceding CI/CD job (e.g. build) to dynamically generate the requirements.txt file and export it as an artifact prior to running the Dependency Scanning job.

OR

• Ensure that your project provides a pipdeptree.json lockfile. Configure the pipdeptree command line utility in a preceding CI/CD job (e.g. build) to dynamically generate the pipdeptree.json file and export it as an artifact prior to running the Dependency Scanning job.

See the enablement instructions for pip for more details and examples.

Pipenv

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Pipenv projects using the gemnasium-python-dependency_scanning CI/CD job to extract the project dependencies by building the application from the Pipfile file or from a Pipfile.lock file if present. The combinations of supported versions for Python and Pipenv are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer does not build the Pipenv project to extract the dependencies. Instead, the project must provide at least a Pipfile.lock file and ideally a pipenv.graph.json file generated by the pipenv graph command. The pipenv.graph.json file is required to generate the dependency graph and enable features like the dependency path. These files are processed by the dependency-scanning CI/CD job to generate a CycloneDX SBOM report artifact. This approach does not require GitLab to support specific versions of Python and Pipenv.

Migrate a Pipenv project

Migrate a Pipenv project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

To migrate a Pipenv project:

• Ensure that your project provides a Pipfile.lock file. Configure the pipenv lock command in your project and either:
  • Permanently integrate the command into your development workflow. This means committing the Pipfile.lock file into your repository and updating it as you’re making changes to your project dependencies.
  • Use the command in a preceding CI/CD job (for example, build) to dynamically generate the Pipfile.lock file and export it as an artifact prior to running the Dependency Scanning job.

OR

• Ensure that your project provides a pipenv.graph.json file. Configure the pipenv graph command in a preceding CI/CD job (for example, build) to dynamically generate the pipenv.graph.json file and export it as an artifact prior to running the Dependency Scanning job.

See the enablement instructions for Pipenv for more details and examples.

Poetry

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Poetry projects using the gemnasium-python-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the poetry.lock file. The combination of supported versions of Poetry and the poetry.lock file are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the poetry.lock file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a Poetry project

Migrate a Poetry project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a Poetry project to use the Dependency Scanning analyzer.

pnpm

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports pnpm projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the pnpm-lock.yaml file. The combination of supported versions of pnpm and the pnpm-lock.yaml file are detailed in the Dependency Scanning (Gemnasium-based) documentation. This analyzer may scan JavaScript files vendored in a npm project using the Retire.JS scanner.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the pnpm-lock.yaml file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job. This analyzer does not scan vendored JavaScript files. Support for a replacement feature is proposed in epic 7186.

Migrate a pnpm project

Migrate a pnpm project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There is no additional steps to migrate a pnpm project to use the Dependency Scanning analyzer.

sbt

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports sbt projects using the gemnasium-maven-dependency_scanning CI/CD job to extract the project dependencies by building the application from the build.sbt file. The combinations of supported versions for Java, Scala, and sbt are complex, as detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer does not build the project to extract the dependencies. Instead, the project must provide a dependencies-compile.dot file generated with the sbt-dependency-graph plugin (included in sbt >= 1.4.0). This file is processed by the dependency-scanning CI/CD job to generate a CycloneDX SBOM report artifact. This approach does not require GitLab to support specific versions of Java, Scala, and sbt.

Migrate an sbt project

Migrate an sbt project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

To migrate an sbt project:

• Ensure that your project provides a dependencies-compile.dot file. Configure the sbt-dependency-graph plugin in a preceding CI/CD job (e.g. build) to dynamically generate the dependencies-compile.dot file and export it as an artifact prior to running the Dependency Scanning job.

See the enablement instructions for sbt for more details and examples.

setuptools

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports setuptools projects using the gemnasium-python-dependency_scanning CI/CD job to extract the project dependencies by building the application from the setup.py file. The combinations of supported versions for Python and setuptools are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer does not support building a setuptool project to extract the dependencies. We recommend to configure the pip-compile command line tool to generate a compatible requirements.txt lockfile. Alternatively you can provide your own CycloneDX SBOM document.

Migrate a setuptools project

Migrate a setuptools project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

To migrate a setuptools project:

• Ensure that your project provides a requirements.txt lockfile. Configure the pip-compile command line tool in your project and either:
  • Permanently integrate the command line tool into your development workflow. This means committing the requirements.txt file into your repository and updating it as you’re making changes to your project dependencies.
  • Use the command line tool in a build CI/CD job to dynamically generate the requirements.txt file and export it as an artifact prior to running the Dependency Scanning job.

See the enablement instructions for pip for more details and examples.

Swift

Previous behavior: Dependency Scanning based on the Gemnasium analyzer does not support Swift projects when using the CI/CD templates or the Scan Execution Policies. Support for Swift is only available on the experimental Swift CI/CD component.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the Package.resolved file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a Swift project

Migrate a Swift project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a Swift project to use the Dependency Scanning analyzer.

uv

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports uv projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the uv.lock file. The combination of supported versions of uv and the uv.lock file are detailed in the Dependency Scanning (Gemnasium-based) documentation.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the uv.lock file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job.

Migrate a uv project

Migrate a uv project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a uv project to use the Dependency Scanning analyzer.

Yarn

Previous behavior: Dependency Scanning based on the Gemnasium analyzer supports Yarn projects using the gemnasium-dependency_scanning CI/CD job and its ability to extract the project dependencies by parsing the yarn.lock file. The combination of supported versions of Yarn and the yarn.lock files are detailed in the Dependency Scanning (Gemnasium-based) documentation. This analyzer may provide remediation data to resolve a vulnerability via merge request for Yarn dependencies. This analyzer may scan JavaScript files vendored in a Yarn project using the Retire.JS scanner.

New behavior: The new Dependency Scanning analyzer also extracts the project dependencies by parsing the yarn.lock file and generates a CycloneDX SBOM report artifact with the dependency-scanning CI/CD job. This analyzer does not provide remediations data for Yarn dependencies. Support for a replacement feature is proposed in epic 759. This analyzer does not scan vendored JavaScript files. Support for a replacement feature is proposed in epic 7186.

Migrate a Yarn project

Migrate a Yarn project to use the new Dependency Scanning analyzer.

Prerequisites:

• Complete the generic migration steps required for all projects.

There are no additional steps to migrate a Yarn project to use the Dependency Scanning analyzer. If you use the Resolve a vulnerability via merge request feature please check the deprecation announcement for available actions. If you use the JavaScript vendored files scan feature, please check the deprecation announcement for available actions.

Changes to CI/CD variables

Most of the existing CI/CD variables are no longer relevant with the new Dependency Scanning analyzer so their values will be ignored. Unless these are also used to configure other security analyzers (for example, ADDITIONAL_CA_CERT_BUNDLE), you should remove them from your CI/CD configuration.

Remove the following CI/CD variables from your CI/CD configuration:

• ADDITIONAL_CA_CERT_BUNDLE
• DS_EXCLUDED_ANALYZERS
• DS_GRADLE_RESOLUTION_POLICY
• DS_IMAGE_SUFFIX
• DS_JAVA_VERSION
• DS_PIP_DEPENDENCY_PATH
• DS_PIP_VERSION
• DS_REMEDIATE_TIMEOUT
• DS_REMEDIATE
• GEMNASIUM_DB_LOCAL_PATH
• GEMNASIUM_DB_REF_NAME
• GEMNASIUM_DB_REMOTE_URL
• GEMNASIUM_DB_UPDATE_DISABLED
• GEMNASIUM_LIBRARY_SCAN_ENABLED
• GOARCH
• GOFLAGS
• GOOS
• GOPRIVATE
• GRADLE_CLI_OPTS
• GRADLE_PLUGIN_INIT_PATH
• MAVEN_CLI_OPTS
• PIP_EXTRA_INDEX_URL
• PIP_INDEX_URL
• PIP_REQUIREMENTS_FILE
• PIPENV_PYPI_MIRROR
• SBT_CLI_OPTS

Keep the following CI/CD variables as they are applicable to the new Dependency Scanning analyzer:

• DS_EXCLUDED_PATHS
• DS_INCLUDE_DEV_DEPENDENCIES
• DS_MAX_DEPTH
• SECURE_ANALYZERS_PREFIX

Continue with the Gemnasium analyzer

While GitLab strongly encourages you to migrate to the new Dependency Scanning analyzer, you might need more time to plan and execute your migration. You can continue using the deprecated Gemnasium analyzer with your existing CI/CD configuration, including all your current CI/CD variables. However, you should consider this only as a temporary solution to extend your migration timeline.

Expected support

To comply with our statement of support, our existing container images for the Gemnasium analyzer must stay available for GitLab 16.x and 17.x Self-Managed instance. This means these container images will still be downloadable and usable until May 2027 at least, when delivering GitLab 20.0 and dropping support for these older major versions.

As GitLab has announced End of Support for this analyzer as of May 2025 (18.0), no support or fixes will be provided.

Disable the new Dependency Scanning analyzer

If you need additional time to evaluate the new Dependency Scanning analyzer, particularly for compliance or internal validation purposes, you can temporarily prevent it from running.

To disable the new analyzer for newly supported languages and package managers, set the CI/CD variable DS_EXCLUDED_ANALYZERS to dependency-scanning in your CI/CD configuration. This setting ensures that only the Gemnasium analyzer will run while you complete your evaluation process.