- Understand the changes
- Identify affected projects
- Migrate to Dependency Scanning using SBOM
- Language-specific instructions
- Changes to CI/CD variables
- Continue with the Gemnasium analyzer
- Disable the new Dependency Scanning analyzer
Migrating to Dependency Scanning using SBOM
- The legacy Dependency Scanning feature based on the Gemnasium analyzer was deprecated in GitLab 17.9 and planned for removal in 18.0.
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
When you migrate, you’ll find several provisions to help prevent disruption to your workflows:
The stable Dependency Scanning CI/CD template (Dependency-Scanning.gitlab-ci.yml
) 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
.
For the latest CI/CD template (Dependency-Scanning.latest.gitlab-ci.yml
), the behavior depends on the version of GitLab you are using:
- In GitLab 17.9, 17.10, and 17.11, it matches the stable template’s behavior.
- From GitLab 18.0 and later, it switches to use the new Dependency Scanning analyzer exclusively for all projects (
DS_ENFORCE_NEW_ANALYZER
is set totrue
by default).
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:
- Remove existing customization for Dependency Scanning based on the Gemnasium analyzer.
- If you have manually overridden the
gemnasium-dependency_scanning
,gemnasium-maven-dependency_scanning
, orgemnasium-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.
- If you have manually overridden the
- Enable the Dependency Scanning using SBOM feature with one of the following options:
- Use either the Dependency Scanning CI/CD template
Dependency-Scanning.gitlab-ci.yml
orDependency-Scanning.latest.gitlab-ci.yml
to run the new Dependency Scanning analyzer:- Keep the Dependency Scanning CI/CD template
include
statement from your.gitlab-ci.yml
CI/CD configuration. - Add the CI/CD variable
DS_ENFORCE_NEW_ANALYZER
and set it totrue
. This variable can be set in many different places, while observing the CI/CD variable precedence. - Adjust your project and your CI/CD configuration if needed by following the language-specific instructions below.
- Keep the Dependency Scanning CI/CD template
- Use the Scan Execution Policies to run the new Dependency Scanning analyzer:
- Edit the configured scan execution policy for Dependency Scanning.
- Add the CI/CD variable
DS_ENFORCE_NEW_ANALYZER
and set it totrue
. This variable can be set in many different places, while observing the CI/CD variable precedence. - 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:
- 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. - Adjust your project and your CI/CD configuration if needed by following the language-specific instructions below.
- Replace the Dependency Scanning CI/CD template’s
- Use your own CycloneDX SBOM document:
- Remove the Dependency Scanning CI/CD template’s
include
statement from your.gitlab-ci.yml
CI/CD configuration. - Ensure a compatible SBOM document is generated by a CI/CD job and uploaded as a CycloneDX SBOM report artifact.
- Remove the Dependency Scanning CI/CD template’s
- Use either the Dependency Scanning CI/CD template
- 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 ago.graph
files. Configure thego mod graph
command from the Go Toolchains in a preceding CI/CD job (for example,build
) to dynamically generate thedependencies.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 thedependencies.lock
file and export it as an artifact prior to running the Dependency Scanning job.
- Permanently integrate the plugin into your development workflow. This means committing the
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 themaven.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 therequirements.txt
file and export it as an artifact prior to running the Dependency Scanning job.
- Permanently integrate the command line tool into your development workflow. This means committing the
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 thepipdeptree.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 thepipenv 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 thePipfile.lock
file and export it as an artifact prior to running the Dependency Scanning job.
- Permanently integrate the command into your development workflow. This means committing the
OR
- Ensure that your project provides a
pipenv.graph.json
file. Configure thepipenv graph
command in a preceding CI/CD job (for example,build
) to dynamically generate thepipenv.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 thedependencies-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 therequirements.txt
file and export it as an artifact prior to running the Dependency Scanning job.
- Permanently integrate the command line tool into your development workflow. This means committing the
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
PIP_REQUIREMENTS_FILE
is replaced with DS_PIPCOMPILE_REQUIREMENTS_FILE_NAME_PATTERN
in the new Dependency Scanning analyzer.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.