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 value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | Package health is not checked | None |
| Report | report | Findings are shown on the merge request, marked (report only) | None |
| Enforce | block | Findings hold the merge | Waiting 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:
| Finding | When |
|---|---|
| Published too recently | The version was published fewer than Minimum version age days ago |
| Deprecated | The 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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Mode (row Package health) | See Modes | Report | Off, Report, Enforce | Policy | Policy manager, company admin, platform admin | controls.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 off | 14 | Company: 0 to 365. Policy editor: Not checked, 3 days, 7 days, 14 days, 30 days, 90 days. API: 0 to 365 | Company; policy override | Company: company admin. Policy: policy manager, company admin | scanning.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 finding | On | On, off (editor: Flag them / Ignore them) | Company; policy override | Same | scanning.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
scanningobject 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
| Status | Message |
|---|---|
| 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_healthwithmodeandoverrides(min_age_days,deprecated). - Company:
scanning.packages(min_age_days,deprecated). - Merge request (
GET /api/v1/merge-requests/{id}): insca_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 indecision.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 →