Skip to main content
Video tutorial · 1:01

Package health

The Package health control flags dependency versions that a merge request brings in and that are not yet established: versions published only days ago, and versions their registry marks deprecated. A hijacked or malicious release is usually found and pulled within days, so waiting until a new version has been public for a while keeps such releases out. Package data comes from deps.dev.

Whether a merge request is checked, and whether a finding holds it, is set per change policy (policy editor, Checks tab, row Package health). The minimum age and the deprecation check are company settings (the company's Scanning tab → Dependencies, card Package health), which a policy can override.

The check runs inside the dependency scan: it reads the same manifests, with the same supported files, path filters and limits, even when the policy's Dependency scan control is off. It uses the same package data as Licenses.

Modes​

Mode (label in the UI)API valueWhat it doesEffect on the merge gate
OffoffPackage health is not checkedNone
ReportreportFindings are shown on the merge request, marked (report only)None
EnforceblockFindings hold the mergeWaiting while the scan runs; Blocked on a too recent or deprecated version, failed package lookups, or a scan that could not be completed

A new policy starts with Report. A policy saved without a mode (for example through the API) is saved with Report, and the editor and the list's chips show it as such.

What is checked​

Every dependency version the change adds, and the new version of every dependency it upgrades or downgrades:

FindingWhen
Published too recentlyThe version was published fewer than Minimum version age days ago
DeprecatedThe registry marks the version deprecated (with Flag deprecated versions on). The registry's reason is shown when it gives one

A version that cannot be checked is counted, not flagged: deps.dev does not know it, its publish date is missing, it is named by a version range, or deps.dev has no data for its ecosystem. Package data is available for the Go, npm, PyPI, Maven, crates.io, NuGet and RubyGems ecosystems. The Go toolchain lines of a go.mod (go, toolchain) are not packages and are skipped. Answers about a package version are reused for up to 7 days. A flagged version accepted by an active exception for its package does not count.

A recent version clears with time​

A version flagged as too recent passes once it reaches the minimum age, without a new scan: the control's message says when ("all pass from 2026-10-30 14:00 UTC"), and the next evaluation of the merge request after that time (any event on it, or the periodic re-check) lets it pass.

Settings​

Company admins change the company's settings on the Scanning tab (PUT /api/v1/companies/{id} with scanning.packages). The policy editor shows the overrides under the Package health row; each starts on Company setting (…).

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Mode (row Package health)See ModesReportOff, Report, EnforcePolicyPolicy manager, company admin, platform admincontrols.package_health.mode (off, report, block)
Minimum version age (days) (policy editor: Minimum version age)A new dependency version published fewer days ago is a finding. 0 turns the age check off14Company: 0 to 365. Policy editor: Not checked, 3 days, 7 days, 14 days, 30 days, 90 days. API: 0 to 365Company; policy overrideCompany: company admin. Policy: policy manager, company adminscanning.packages.min_age_days; controls.package_health.overrides.min_age_days
Flag deprecated versions (policy editor: Deprecated versions)A version its registry marks deprecated is a findingOnOn, off (editor: Flag them / Ignore them)Company; policy overrideSamescanning.packages.deprecated; controls.package_health.overrides.deprecated

With the age check off and deprecated versions ignored, the control finds nothing.

Notes:

  • Both settings take effect at the next scan (a new commit or a re-scan).
  • The company's scanning object is saved as a whole: fields left out take their defaults.
  • What a failed scan or a failed lookup does is the dependency scan's When the scan cannot finish setting (see Dependency scan).

What the control says​

StatusMessage
Pending"Checking the health of new dependencies."
Passed"No recently published or deprecated new dependencies." (with "N could not be checked (not known to deps.dev)." when some could not be)
Failed"N new dependency version(s) published too recently (all pass from … UTC)." and/or "N new dependency version(s) deprecated by their registry."
Failed"The package data of N new dependency version(s) could not be read from deps.dev: … Rescan once deps.dev answers."
Failed"The dependency scan could not be completed: … Fix the cause and rescan."

When it runs​

With the dependency scan: once per commit, on Re-scan on the merge request page's Dependency scan (SCA) card (POST /api/v1/merge-requests/{id}/rescan with {"scan": "sca"}), and after a failure when the company or policy retries automatically. A scan of the latest commit made while the control was off runs again once the policy turns it on. See Dependency scan.

What the merge request shows​

In the Dependency scan (SCA) card, a Package health section shows No recently published or deprecated new dependencies., or each flagged version with published and when, or deprecated and the registry's reason. Versions that could not be checked are counted ("N new versions are not known to deps.dev (not checked).").

The Merge Pilot: Dependency Scan comment in the VCS includes a Package health table (package, version, finding).

GitLab and GitHub​

The check is the same on both.

Audit​

The result is part of the sca_scan entry (with a package_findings count), written when the result changes. Re-scans are sca_rescan. See Audit log.

API​

  • Policy: controls.package_health with mode and overrides (min_age_days, deprecated).
  • Company: scanning.packages (min_age_days, deprecated).
  • Merge request (GET /api/v1/merge-requests/{id}): in sca_scan, packages_checked, package_min_age_days, package_findings (package, version, ecosystem, manifest, published_at, recent, deprecated, deprecated_reason), packages_unknown, lookup_failed, lookup_error; and the result in decision.controls (control: "package_health").

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Keep Deprecated Packages OutYouTube ↗