Project analysis
A project analysis reads a project's default branch as a whole, not a merge request: it finds every dependency manifest, lists the dependencies, looks them up for known vulnerabilities and licenses, and keeps the result. It is what the vulnerability inventory and the SBOM are built from.
Analyses are shown on the project's Security tab; the tab's parts are listed on Project page → Security. This page explains how an analysis works.
What starts one
| Start | When | Shown in the history as |
|---|---|---|
| Run analysis | A company admin or platform admin selects it on the Security tab | By <user> |
| A merge | A merge request that changed a dependency manifest, a file that may refer to container images or an infrastructure file (those two only while their inventory is on) merged into the default branch, while the company's Update it when a merge request that changes a dependency manifest, a file that refers to container images or an infrastructure file merges is on (not for imported past merge requests) | After merge !N |
| A direct change | A push without a merge request changed a dependency manifest, a file that may refer to container images or an infrastructure file (those two only while their inventory is on) on the default branch, while Refresh the vulnerability inventory when one changes a dependency manifest is on | After a direct change to <branch> |
A merge or direct change that arrives while an analysis of the project runs waits for it and runs after. The background advisory check (every 24 hours by default) does not run an analysis: it looks the dependencies recorded by the last analysis up again, without reading the repository, and is not listed in the history (see Vulnerability inventory).
What it reads
- The commit. The head of the default branch when the analysis starts; the whole analysis reads that one commit (Ref: and Commit: on the tab).
- The manifests. The branch's file list is read, and every supported dependency manifest kept (the files listed on Dependency scan → Supported manifests), except:
- manifests under the company's Blocked paths, or outside its Allowed paths when it sets any (company Scanning tab → Dependencies → Path filters);
- manifests under the project's Excluded paths (see Project page → Excluded paths);
- a
package.jsonbeside its npm lockfile.
- Only what changed. A manifest whose content is the same as at the last analysis is not read again: its dependencies are taken from then. The history shows how many were read (N manifests read).
- The lookups. Each dependency with an exact version is looked up for vulnerabilities in OSV.dev (answers are reused for up to 24 hours), with the CISA KEV and EPSS marks; every dependency is looked up for its licenses in deps.dev (answers reused for up to 7 days).
- The inventory. The result updates the project's vulnerability inventory: new findings are opened, findings it shows gone are fixed (see How findings are fixed), and new ones from the company's notification threshold are announced. A project's first analysis, however it started, is the inventory's baseline: nothing in it is new or announced.
A manifest that cannot be read keeps the dependencies it had at the last analysis, so nothing it had is taken as fixed.
Limits
| Limit | Value | When it is reached |
|---|---|---|
| Manifests per analysis | 50 | The first 50 by path are analysed; findings in the others stay as they were |
| Dependencies looked up | The company's Max dependencies per project analysis (20,000 by default) | Shared evenly among the manifests (a small manifest gets all its dependencies); the dependencies left out are looked up in turn by the next analyses |
| Time per lookup | The company's Project analysis timeout (seconds) (90 by default) | The vulnerability lookup fails (and the result says so); a license lookup that times out leaves those licenses unknown |
| Vulnerabilities listed | 500 | The analysis lists the 500 most severe; the counts and the inventory use all of them |
| Running time | 65 minutes (an analysis also scans the branch's images and infrastructure files while their inventories are on, which can take long) | An analysis still running is marked Failed (The analysis did not finish within 65 minutes and was stopped. …, or The analysis did not start within 65 minutes (Merge Pilot was busy with other work) and was stopped. … when it never started); it can be run again at once |
The two company settings are on the company's Scanning tab → Dependencies (see Scanning).
Results may be incomplete
When an analysis could not see everything, the Last analysis card shows Results may be incomplete with each reason. An incomplete analysis still completes; nothing it did not see is taken as fixed.
| Reason (as shown) | When | API value |
|---|---|---|
| Repository tree was truncated (limit: 5,000) on GitLab; no limit is shown on GitHub, which does not say where it cut the list | The VCS returned only part of the branch's file list; the well-known manifest names at the repository root are tried as well | tree_truncated:5000 (GitLab), tree_truncated (GitHub) |
| Manifest limit reached: the first manifests by path were analysed, and findings in the others stay as they were (limit: 50) | More than 50 manifests | max_manifests_exceeded:50 |
| N manifests could not be read | A manifest could not be fetched or parsed | manifests_unreadable:N |
| Dependency limit reached; set it on the company under Scanning → Dependencies (limit: N) | More dependencies than the company's limit | max_deps_exceeded:N |
| N dependencies were not checked this time (each manifest got an even share of the limit; the next analyses check the rest in turn) | The same; the number left out | deps_not_checked:N |
| N dependencies have no exact version and were not checked for vulnerabilities | Named by a version range (commit the lockfile to check the versions in use) | unpinned_deps:N |
| N dependencies are in an ecosystem the vulnerability database does not cover | Such as CocoaPods | unsupported_deps:N |
| The vulnerability lookup failed; run the analysis again | OSV.dev could not be asked, or did not answer in time | vulnerability_lookup_failed |
| Maximum vulnerability limit reached (limit: 500) | More than 500 vulnerabilities | max_vulns_exceeded:500 |
| N dependencies have no license data | deps.dev has no license for them or does not cover the ecosystem, the dependency has no exact version, or the lookup failed | unresolved_licenses:N |
| The dependencies could not be saved; the next analysis reads every manifest again | Recording the dependencies failed | snapshot_not_saved |
In the Licenses list, an unknown license says why: Unknown (not in deps.dev), Unknown (ecosystem not supported), Unknown (no exact version) or Unknown (lookup failed); None declared when the package declares none.
Failures, retry and cooldown
A failed analysis shows Failed and the reason (for example a VCS error or a timeout). Another analysis cannot be started:
| While | Answer |
|---|---|
| One is running (one running for more than 65 minutes is marked Failed first, and the new one starts) | analysis already running |
| Within 5 minutes after the last one completed | the last analysis completed less than 5 minutes ago; run it again in N minutes |
| Within 5 minutes after the last one failed, unless the failure was temporary | the last analysis failed less than 5 minutes ago; run it again in N minutes |
After a temporary failure (a timeout, a network error, a VCS server error, the 65-minute limit) the button reads Retry and works at once. The 5 minutes count from any analysis of the project, including one started by a merge or a direct change.
A VCS rate limit does not fail an analysis: it waits for the limit to reset and starts over.
The Stale badge marks a completed analysis older than 7 days. Nothing reruns it on its own: merges, direct changes and Run analysis do.
Analysis history
Analysis history lists the project's analyses, newest first:
| Column (label in the UI) | Shows |
|---|---|
| Date | When it started |
| Status | Running, Completed or Failed |
| Duration | How long it took |
| Manifests | The manifests analysed |
| Deps | The dependencies found |
| Vulns | The vulnerabilities found |
| Run | After merge !N, After a direct change to <branch> (linked to the direct change when the company recorded it; plain text when not) or By <user>, with N manifests read |
| What changed | N new, M gone: the findings this run opened (or opened again) and fixed in the vulnerability inventory |
Selecting What changed lists those same findings: the new ones and the gone ones, each with its severity, advisory and package@version, so the list always matches the counts in its row. A vulnerability is matched by its advisory ID or any alias, so an advisory that changes its preferred ID is neither new nor gone. At most 500 of each are listed; past that each list ends with Showing N of M. A project's first analysis is the baseline and lists nothing new.
The details of analyses older than the company's Keep fixed vulnerabilities, old analyses and direct changes (days) (365 by default) are deleted once a day, except those of the project's latest completed analysis (the SBOM's source); their summaries and counts stay in the history, and What changed then gives the counts and says the list is no longer kept (N new, M gone. The details are no longer kept: they were removed after the company's retention period.), not that nothing changed.
Who may do what
| Action | Who |
|---|---|
| Read the analyses, their details and history, export the SBOM | Everyone in the company |
| See the inventory (the Dependencies view of the Security tab) instead of the analysis's own vulnerability list | Company admins, policy managers, auditors, platform admins |
| Run analysis, Excluded paths | Company admins, platform admins |
API
All paths start with /api/v1. Every role of the company may read; starting needs a company admin or platform admin.
| Request | What it does |
|---|---|
POST /projects/{id}/analysis | Starts one. 202 with the analysis; 429 while one runs or within the 5 minutes (then with Retry-After, in seconds); 409 when one was started at the same moment |
GET /projects/{id}/analysis | The latest analysis (null when none ran) |
GET /projects/{id}/analysis/history | The analyses, newest first, with page and page_size |
GET /projects/{id}/analysis/{aid} | One analysis |
GET /projects/{id}/analysis/{aid}/details | Its lists: type = deps, vulns or licenses (none: all three) |
GET /projects/{id}/analysis/{aid}/diff | The findings it opened and fixed: new and fixed (at most 500 each), new_total and fixed_total (its new_findings and fixed_findings), incomplete (a list holds fewer than its total), unavailable (the lists were removed with its details), and previous (the completed analysis before it; absent for the first) |
An analysis has id, status (running, completed, failed), ref, commit_sha, triggered_by, cause (merge, direct; absent when started by hand), mr, change (a direct change: branch, after, pusher, and id when the company records direct changes), manifests_found, manifests_read, total_deps, total_vulns, new_findings, fixed_findings, severity_counts, total_license_entries, unique_license_exprs, unique_license_atoms, license_expr_summary, license_atom_summary, truncation_reasons, started_at, completed_at, duration_ms and error.
Audit
| Action | When | Who |
|---|---|---|
analysis_triggered | Someone selected Run analysis | The person |
project_analysis | An analysis completed, with its counts (manifests, manifests read, dependencies, vulnerabilities, new and fixed findings, license entries) and who or what started it | Merge Pilot |
update_project_sca_exclude | A project's excluded paths changed | The person |
A failed analysis writes no audit entry; it shows on the tab. See Audit log → Projects.
Related pages
- Project page → Security: the tab, part by part.
- Vulnerability inventory.
- SBOM export.
- Scanning: Max dependencies per project analysis, Project analysis timeout (seconds) and Vulnerability tracking.
- Jobs:
project_analysisandvuln_refresh.