Dependency scanning auto-remediation

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Beta

Dependency scanning auto-remediation opens a merge request to bump a vulnerable dependency to a non-vulnerable version when one is available. A service account creates the merge request without any human input, which then goes through the standard review and approval process.

In beta, dependency scanning auto-remediation supports two independently configurable capabilities:

  • Dependency version bumps: GitLab opens merge requests that update the vulnerable dependency.
  • Agentic breaking-change resolution: When a version bump causes a pipeline failure due to a breaking change, GitLab Duo attempts to resolve it. For more information, see enable agentic breaking-change resolution.

For the generally available roadmap, see epic 19244.

Security configuration profiles also support this flow. To turn on and configure the flow across multiple projects and groups at once, use the automated triage and remediation profile.

Turn on dependency scanning auto-remediation

Prerequisites:

  • Dependency scanning must be enabled and producing results. The scan must run, and the results must be reported on the default branch.
  • The project must use a supported package manager.
  • A dependency scanning auto-remediation profile must be attached to the project. For instructions, see dependency scanning auto-remediation profile.
  • The runner must accept untagged jobs, unless you set runner tags on the profile. GitLab generates the auto-remediation job itself and does not use the project’s .gitlab-ci.yml configuration for it, so default:tags does not apply.
  • The runner must allow privileged mode. The auto-remediation job uses a docker:28-dind service. For more information, see use Docker to build Docker images.
  • The runner must be able to pull the auto-remediation orchestrator image from registry.gitlab.com and the docker:28-dind image.

To trigger vulnerability detection and auto-remediation, run a pipeline. Dependency scanning auto-remediation triggers automatically when GitLab detects vulnerabilities with available fixes.

How dependency version bumps work

The dependency scanning auto-remediation profile controls this behavior. With the default profile:

  • Severity threshold: GitLab remediates vulnerabilities at or above high severity.
  • Cooldown period: GitLab excludes fix versions released in the last seven days.
  • Upgrade policy: GitLab proposes only patch and minor version bumps, unless agentic breaking-change resolution is enabled.
  • Open merge request limit: A maximum of 30 auto-remediation merge requests can be open per project at a time. GitLab does not create new merge requests until existing ones are merged or closed.

After each pipeline, GitLab checks dependency scan results against these values. For each eligible vulnerability:

  1. GitLab determines the nearest non-breaking upgrade path.
  2. A service account opens a merge request that updates the relevant manifest file.
  3. GitLab does not assign a reviewer. To have the Code Owners of the updated files requested as reviewers, turn on automatic reviewer assignment.
  4. The merge request goes through your project’s standard approval workflow.

During beta, GitLab processes three vulnerabilities at a time, starting with the highest severity finding.

The availability of the scheduler rate limit is controlled by a feature flag. For more information, see the history.

When the scheduler rate limit is enabled, GitLab starts at most one scheduler run for each project every five minutes. Runs that fill a slot freed by a dismissed update have their own limit of one every five minutes. For more information, see non-configurable rate limits.

Merge request titles and commit messages

By default, an auto-remediation merge request has a title like Security: Update rack from 2.0.9 to 2.2.0. The commit subject is Update rack.

If the default branch follows Conventional Commits, GitLab uses that format for both the merge request title and the commit subject. For example:

build(deps): [security] update rack from 2.0.9 to 2.2.0

GitLab samples up to 20 of the most recent non-merge commits on the default branch, skipping commits by the auto-remediation service account. GitLab searches no further back than 50 non-merge commits. The project counts as using Conventional Commits when at least 30% of these commits start with one of these types, with any capitalization: build, chore, ci, docs, feat, fix, perf, refactor, style, or test. The type can have an optional scope and an optional ! breaking-change marker.

Otherwise, GitLab uses the default format. For example, projects that use emoji or a custom prefix such as deps: get the default format.

For projects that use Conventional Commits, GitLab copies the style of the matching commits:

  • The type is chore if the matching commits use chore and never build. Otherwise, the type is build.
  • The type is capitalized, as in Build(deps):, if most of the matching commits capitalize the type.
  • The scope is always deps.
  • The text after (deps): reads [Security] Update if most of the matching commits start the subject with a capital letter, and [security] update otherwise.

If a Conventional Commits title is longer than 72 characters, GitLab leaves out the old version from the title and commit subject, as in build(deps): [security] update rack to 2.2.0.

When GitLab updates an open merge request, it keeps the Conventional Commits style the merge request was created with, even if the default branch history changes. A merge request with the default format switches to Conventional Commits the next time GitLab updates it, if the default branch then follows the convention.

Enable agentic breaking-change resolution

When a version bump causes a pipeline failure because of a breaking change, GitLab Duo can attempt to resolve the breaking change automatically. This capability is separate from the dependency version bump capability and has its own toggle.

Prerequisites:

  • You must have GitLab Duo available for the project.

To enable agentic breaking-change resolution, use the Projects API to set duo_dependency_bump_breaking_changes_enabled to true for the project.

Configure scheduler concurrency

Administrators can limit how many auto-remediation scheduler jobs run concurrently across the Sidekiq fleet. Use the security_update_scheduler_max_concurrency application setting to set the cap. The default is 30, and the value is capped at 200. Set the value to 0 to pause scheduling.

Set runner tags for auto-remediation jobs

If your runner fleet uses tags, you can tag the auto-remediation job so that only runners with matching tags pick it up. By default, the job is untagged. GitLab-recommended profiles cannot be edited, so you must create your own profile.

Prerequisites:

  • The Security Manager, Maintainer, or Owner role for the group.

To set runner tags:

  1. Create a dependency scanning auto-remediation profile with the securityScanProfileCreate mutation and set runnerTags:

    graphql
    mutation {
      securityScanProfileCreate(input: {
        namespaceId: "gid://gitlab/Group/123",
        scanType: DEPENDENCY_SCANNING_POST_PROCESSING,
        name: "Auto-remediation on tagged runners",
        description: "Runs auto-remediation jobs on runners tagged docker and linux",
        triggers: [
          {
            triggerType: SBOM_INGESTED,
            configuration: {
              dependencyScanningPostProcessing: {
                autoRemediation: {
                  runnerTags: ["docker", "linux"]
                }
              }
            }
          }
        ]
      }) {
        scanProfile {
          id
          name
        }
        errors
      }
    }

    Settings you do not specify keep their default values.

  2. Attach the profile to your projects or groups. For instructions, see apply a profile with the GraphQL API.

To change the tags later, update your profile with the securityScanProfileUpdate mutation. The update replaces the profile’s triggers and their settings, so include every trigger and setting you want to keep, not only runnerTags.

The runnerTags setting has these limits:

  • Up to 20 tags.
  • Each tag is 1 to 255 characters long.
  • Tags cannot be duplicated.
  • Tags cannot contain commas, quotes (" or '), or $.
  • Tags cannot start or end with a space.

The automated triage and remediation profile accepts the same field under triageAndRemediation.sbomIngested.autoRemediation.runnerTags.

Supported package managers

Dependency scanning auto-remediation supports the following package managers:

Language Package Manager Files
Ruby Bundler Gemfile, Gemfile.lock
Java Maven pom.xml
Java Gradle build.gradle, build.gradle.kts
Python pip, pipenv, poetry, setuptools, uv requirements.txt, Pipfile, pyproject.toml, setup.py, uv.lock
JavaScript / TypeScript npm, yarn, pnpm, bun package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock
Go Go modules go.mod, go.sum
Rust Cargo Cargo.toml, Cargo.lock
.NET NuGet *.csproj, packages.lock.json
Dart and Flutter Pub pubspec.yaml, pubspec.lock
Swift Swift Package Manager Package.swift, Package.resolved

Support for additional ecosystems is proposed in epic 19244.

For .NET, dependency scanning only detects NuGet dependencies from a committed packages.lock.json. Projects without one produce no NuGet findings, so auto-remediation has nothing to act on. To generate the lock file, set RestorePackagesWithLockFile in your project file and commit the result.

For Dart and Flutter, dependency scanning only detects Pub dependencies from a committed pubspec.lock. Projects without one produce no Pub findings, so auto-remediation has nothing to act on. Generate the lock file by running dart pub get or flutter pub get, and commit the result. Pub auto-remediation jobs also take several minutes longer than other ecosystems, because the updater sets up a Flutter SDK before resolving dependencies, even for pure-Dart projects.

For Swift, dependency scanning only detects dependencies from a committed Package.resolved. Projects without one produce no Swift findings, so auto-remediation has nothing to act on. Generate the lock file by running swift package resolve, and commit the result. Auto-remediation skips dependencies pinned to a branch or a commit, because Package.resolved records no version for them.

Service account permissions

The first time dependency scanning auto-remediation runs on a project, GitLab creates a service account for the project named GitLab Dependency Management. GitLab reuses this account for every subsequent auto-remediation merge request on the project, so each project has exactly one.

GitLab adds the service account to the project as a Guest member. This membership makes the account a member of the project, but grants no other permission. A dedicated internal role then grants the account the following abilities:

  • Clone the repository.
  • Push a branch.
  • Create and update merge requests.
  • Create pipelines.

This internal role, not the Guest membership, bounds what the account can do. The account holds no broader role because the design grants these abilities directly and narrowly, instead of giving an automated account the Developer role on every project that turns the feature on. For the full rationale behind this design, see ADR 003: Single service account model.

The internal role does not override the visibility a project sets for merge requests. If a project limits merge requests to project members, only users with at least the Reporter role can create them. Auto-remediation then creates no merge requests on that project. For the fix, see auto-remediation creates no merge requests.

Pipelines on auto-remediation merge requests run as this service account. If a job needs permissions beyond what that role grants, the job fails, even though the same pipeline succeeds when a person with the Developer role runs it. For example:

  • Pushing a container image to the project container registry requires the Developer role. Pulling an existing image from the project container registry works with the service account’s permissions.
  • Reading the project package registry requires the Reporter role.

A project that uses Auto DevOps hits the container registry case, because the Auto DevOps build job pushes an image.

To let these jobs run, a user with at least the Maintainer role can grant the service account the Developer role on the project. For instructions, see auto-remediation pipeline jobs fail with permission errors.

Known issues

During the beta phase:

  • Cooldown period: GitLab does not propose a fix version released in the last seven days, to reduce the risk of remediating to a version that is later found to be broken or malicious.
  • Version bump scope: Only patch and minor version bumps are proposed. Major version upgrades, which are more likely to introduce breaking changes, are not attempted unless agentic breaking-change resolution is enabled.
  • One vulnerability per pipeline run: Each pipeline run targets a single vulnerability with an available fix. Batching multiple fixes into one merge request is proposed in epic 19244.
  • No fix available: If no non-breaking fix version exists for a vulnerability, no merge request is created for that finding.
  • Merge request creation depends on a successful pipeline. GitLab creates the dependency-management/<dependency>-<major-version>.x branch before it runs the auto-remediation pipeline on that branch, and creates the merge request only after that pipeline succeeds. A dependency-management/ branch that has no merge request and no commit that changes a manifest file indicates that the pipeline did not succeed. Check the status of the pipeline on that branch.

Troubleshooting

Auto-remediation pipeline jobs fail with permission errors

Pipeline jobs on auto-remediation merge requests run as the GitLab Dependency Management service account, which gets its abilities from an internal role rather than from the Guest role it also holds. This internal role does not cover everything a project pipeline might need. For more information, see service account permissions. A job that needs permissions beyond what that role grants fails, even though the same job succeeds when a person with the Developer role runs it. The error differs by job. For example, a job that pushes an image to the project container registry receives a denial, and a job that reads the project package registry receives a 403 error.

To work around this issue, a user with at least the Maintainer role can grant the service account the Developer role for the project:

  1. In the left sidebar, select Search or go to and find your project.
  2. Select Manage > Members.
  3. Find the GitLab Dependency Management member.
  4. Change its role to Developer.

This action grants the service account the full Developer role on the project. Make this change only if your pipeline needs it. The change applies only to this project. It persists, so subsequent auto-remediation merge requests on the project get pipelines that work. Re-run the failed pipeline to pick up the change.

Auto-remediation creates no merge requests

Dependency scanning runs on the default branch, but auto-remediation creates no merge requests when the GitLab Dependency Management service account cannot create merge requests in the project. On that project:

  • GitLab creates and updates no dependency-management/ branches.
  • Open auto-remediation merge requests are no longer refreshed.
  • If you start a remediation from the vulnerability report, the report shows the error Service account cannot create merge requests in this project.

The same error has several causes. On GitLab Self-Managed, an administrator can find the cause in the denial_reason field of the DependencyManagement: service account cannot create merge requests entry in application_json.log.

Cause denial_reason Resolution
Merge requests are set to Only Project Members. merge_requests_private Grant the service account the Reporter role.
Merge requests are turned off for the project. merge_requests_disabled Turn on merge requests for the project.
The repository is turned off for the project. repository_disabled Turn on the repository for the project.
The project is archived, or the service account was removed from the project. access_denied Unarchive the project, or add the service account back as a member.
The namespace is read-only. access_denied Remove the read-only state of the namespace.

The service account is a Guest member of the project. When merge requests are set to Only Project Members, only users with at least the Reporter role can create them. The internal role of the account does not override this requirement. For more information, see service account permissions.

To grant the service account the Reporter role, a user with at least the Maintainer role can:

  1. In the top bar, select Search or go to and find your project.
  2. Select Manage > Members.
  3. Find the GitLab Dependency Management member.
  4. Change its role to Reporter.

Alternatively, set the visibility of merge requests to Everyone With Access. On a public project, this setting lets users who are not project members create merge requests too.

Auto-remediation picks up any of these changes the next time dependency scanning runs on the default branch.