Dependency sources
The Dependency sources control checks where the dependencies a merge request adds or changes are fetched from. A vulnerability scan looks at which package version is used; this control looks at where it comes from:
- A manifest changed without its lockfile. Installs that follow the lockfile (
npm ci,pnpmandyarnin CI,cargo --lockedand the like) then fail, or use versions the manifest no longer names, and the versions nobody reviewed are fetched later. - A lockfile entry fetched from a registry that is not allowed. A package of the same name on another registry is the classic dependency confusion attack, and a hand-edited lockfile can point one package at any host. The control checks every new or changed lockfile entry, so a lockfile changed on its own is checked too.
- Dependencies taken from a git repository, a URL or a local path, which bypass the registry and the checks that come with it.
- pip index options that add or replace package indexes, or turn off TLS checks.
It runs inside the dependency scan, so it needs no extra job. In the policy it is the Dependency sources row of the Checks tab (API: controls.sources). The registries and choices are company settings (the company's Scanning tab → Dependencies, card Dependency sources), which a policy can override.
How it checks
- The changed files of the merge request are listed (deleted files are skipped; a deleted lockfile still counts as a changed lockfile).
- Each changed dependency file is read at the merge base (the target branch, or the file's old path when it was renamed) and at the merge request's head commit. A new file has no base: all its entries are new.
- Only entries that are new or changed at the head count: an entry whose package, version, kind of source, host, address and ref are all the same as in the base is not checked again. Index options that are already in the base are not checked again either.
- Each new or changed entry is checked against the rules below and the settings.
The company's (or policy's) dependency scan path filters apply: a file outside the allowed paths, or inside the blocked paths, is not read (see Dependency scan).
Rules
| Rule | Label on the merge request | What is found | Why it matters |
|---|---|---|---|
lockfile-missing-update | Lockfile not updated | A manifest changed, its lockfile exists at the head commit, and the lockfile did not change. A package.json or go.mod whose dependencies are the same as before is not a finding (see below). When the repository keeps no lockfile for the manifest, there is no finding | The installed versions come from the lockfile; the manifest change is either not applied or applied without review |
registry-not-allowed | Registry not allowed | A new or changed lockfile entry fetched from a host that is not an allowed registry for its ecosystem | Dependency confusion: a package of the same name on another registry, or a lockfile entry pointed at another host |
source-git | Git source | A dependency taken from a git repository (unless git dependencies are allowed) | It bypasses the registry; its content is whatever the repository holds at that ref |
source-url | URL source | A dependency downloaded from an archive URL (unless URL dependencies are allowed) | It bypasses the registry; the address can serve other content later |
source-path | Local path | A dependency taken from a local path or a link: a file: or link: dependency, a directory dependency, a go.mod replace whose target is a ./ or ../ directory (unless local path dependencies are allowed) | The code comes from the repository or the machine running the build, not from a published package |
extra-index-url | Extra index | A requirements file adds --extra-index-url for a host that is not an allowed PyPI registry | pip may install a package of the same name from either index: pip's own documentation calls this unsafe, a dependency confusion risk |
index-url-not-allowed | Index not allowed | A requirements file's -i / --index-url / --pypi-url, or a Pipfile.lock source, points at a host that is not an allowed PyPI registry | Every package is then fetched from that index |
find-links | Find-links | A requirements file's -f / --find-links points at a host that is not allowed, or at a local directory (a local directory passes when local path dependencies are allowed) | pip looks for packages at that location too |
trusted-host | Trusted host (no TLS check) | A requirements file's --trusted-host | pip then fetches from that host "even though it does not have valid or any HTTPS": packages arrive without TLS verification. It is a finding whatever the host |
source-unknown-form | Source unknown (review) | An entry whose source is written in a form Merge Pilot does not read (see Formats) | Informational: it is listed so someone looks at it, and never fails the check. When the entry names a host that is not allowed, it is reported as registry-not-allowed instead |
Packages of the same workspace (yarn workspace:, uv virtual, and npm links to a folder inside the repository) are built from the repository itself and are not findings. A local path counts only when it is new to the merge request: a version bump of the project's own crate or package is not a finding. A yarn patch: entry is a local patch over another package and is not checked.
A manifest changed without its lockfile
A manifest is paired with the lockfiles its package managers write next to it, in the same directory:
| Manifest | Lockfiles |
|---|---|
package.json | package-lock.json, npm-shrinkwrap.json, yarn.lock, pnpm-lock.yaml, bun.lock |
pyproject.toml | poetry.lock, uv.lock, pdm.lock |
Pipfile | Pipfile.lock |
Cargo.toml | Cargo.lock |
Gemfile | Gemfile.lock |
composer.json | composer.lock |
go.mod | go.sum |
- When any of the paired lockfiles changed in the merge request (or was deleted), there is no finding.
- Otherwise each paired lockfile is looked up at the head commit. When none exists, the project keeps no lockfile and there is no finding. When some exist, the finding names them.
- The same dependencies: for
package.json, a change that leaves thedependencies,devDependencies,optionalDependencies,peerDependencies,bundleDependencies(orbundledDependencies) andoverridessections as they were (only the scripts, the version or other fields changed) is not a finding. Forgo.mod, a change that leaves therequire,replaceandexcludedirectives as they were (only thegoortoolchainline changed) is not a finding. Other manifests count on any change.
Registries
A registry entry is allowed when its host is on the allow-list of its ecosystem: the public registries below, plus the company's (or policy's) own, unless Only the listed registries is on.
| Ecosystem | Public registries allowed by default |
|---|---|
| npm (npm, yarn, pnpm) | registry.npmjs.org, registry.yarnpkg.com |
| PyPI (pip, Pipenv, Poetry, uv) | pypi.org, files.pythonhosted.org |
| crates.io | github.com/rust-lang/crates.io-index, index.crates.io |
| RubyGems | rubygems.org |
| Packagist | repo.packagist.org, api.github.com, github.com |
- An entry is
host,host:portorhost/path. The host (and port) must match exactly, ignoring case; a path, when given, must be the address's path or a parent of it. Sogithub.com/rust-lang/crates.io-indexallows that one index ongithub.com, not every repository there. A scheme (https://) and a trailing slash are dropped when the entry is saved; credentials, a query or wildcards are refused. - An entry whose lockfile names no host is fetched from the package manager's configured registry, which the lockfile does not record. It is not checked against the list: pnpm entries with only an integrity hash, yarn (berry)
npm:entries, Poetry packages without a source, Pipfile.lock packages without an index, and yarn (classic) or npm (version 1) entries without a resolved address. - Packagist:
composer.lockrecords a download and a repository address for every package, Packagist ones included. Both are checked as registry hosts (not as git or URL sources), which is whyapi.github.comandgithub.comare allowed by default. Apathpackage is a local path. - Go has no registry check: where Go modules are downloaded from is set on the machine that builds, not in the repository. Only a
replaceto a local directory is checked.
Files read
| File | What is read |
|---|---|
package-lock.json, npm-shrinkwrap.json | Version 2 and 3: each package's resolved address and link flag. Version 1: each dependency's version (git, tarball, file: sources) and resolved address. The project itself is skipped |
package.json | Dependencies named by git (git+…, github:…), an http(s) tarball, file: or link:, in dependencies, devDependencies, optionalDependencies and peerDependencies. Version ranges are resolved through the registry, which only the lockfile records |
yarn.lock (classic) | Each entry's resolved address; file: and link: entries; offline-mirror tarballs as local paths |
yarn.lock (berry) | npm: (with its archive address when the lockfile has one), git #commit=, workspace:; other protocols are an unknown form |
pnpm-lock.yaml | Every document of the file: integrity-only entries, tarball addresses (git-hosted ones as git), type: git, type: directory, and link: dependencies of the importers; other resolution types are an unknown form |
requirements*.txt | Each requirement (registry, name @ URL, git VCS URLs, archive URLs, local paths, -e) and the options -i / --index-url / --pypi-url, --extra-index-url, -f / --find-links, --trusted-host. Other VCS schemes are an unknown form. Files named with -r or -c are not followed: they are read only when they changed in the merge request too, and are named requirements*.txt |
Pipfile.lock | The sources in _meta.sources, and each package's index, git, file or path |
poetry.lock | Each package's [package.source]: none (PyPI), legacy (a registry), git, directory, file, url |
uv.lock | Each package's source: registry, git, url, path, directory, editable (a local path), virtual (the workspace) |
Cargo.lock | Each package's source: registry+…, sparse+…, git+…. A package without a source (the project's own crates and path dependencies) counts as a local path |
Gemfile.lock | The GEM, GIT and PATH sections. A PLUGIN SOURCE, or a GEM section with several remotes, is an unknown form whose hosts are still checked |
composer.lock | Each package's download (dist) and repository (source) addresses, and path packages |
go.mod | replace directives whose target is a local directory |
bun.lock and pdm.lock count for lockfile pairing only: their sources are not read, because their format could not be verified from their publishers' documentation.
Limits
- At most 20 changed dependency files are checked per merge request. When more are changed, the first 20 are checked and the check fails, saying so; with the company's More … than the limits set to check the first ones, it checks those and names what it did not look at instead.
- A file over 5 MB, or with more than 50,000 entries, fails the check; nothing is cut short.
- A file that cannot be read or does not parse at the head commit fails the check. A base version that does not parse is read as empty: every head entry is then checked.
- When the VCS lists only part of the changed files, the check fails: a changed dependency file may have been missed. With the company's The VCS lists only part of the changed files set to Check what was listed, it checks the files listed instead.
- Credentials in an address (
user:password@, a token) are removed before anything is stored, and the query string and fragment are dropped from the addresses shown. A finding names the host.
The 20-file limit and a cut-short file list follow the company's When a scan cannot see everything (see Scanning), as the dependency scan does; a policy can set its own. A check failed this way is final: it is not retried by itself, and says Trying again would not change this. What a check left out is named in the control's reason (Not looked at: …).
A failed check fails the control, never passes it. What happens next follows the dependency scan's When the scan cannot finish setting (see Dependency scan).
Modes
| Mode (label in the UI) | API value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | Sources are 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 finding (informational ones excepted) or a check 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.
Settings
Company admins change the company's settings on the Scanning tab, section Dependencies, card Dependency sources (PUT /api/v1/companies/{id} with scanning.sources). The policy editor shows the overrides under the Dependency sources 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 Dependency sources) | See Modes | Report | Off, Report, Enforce | Policy | Policy managers, company admins, platform admins | controls.sources.mode (off, report, block) |
| Private registries: npm registries, PyPI registries, crates.io registries, RubyGems registries, Packagist registries (policy editor: Registries, then Company setting (…) or This policy's list) | Registries your package managers use besides the public ones. A lockfile entry fetched from any other host is a finding | Empty (the public registries only) | host, host:port or host/path, one per line (policy editor: separated by commas) | Company; policy override | Company: company admins, platform admins. Policy: policy managers, company admins, platform admins | scanning.sources.registries; controls.sources.overrides.registries (a map per ecosystem: npm, PyPI, crates.io, RubyGems, Packagist) |
| Only the listed registries (policy editor: Public registries, Allowed / Not allowed (only the listed ones)) | The public registries are not allowed either, in every ecosystem: list each registry that is (for example a mirror that proxies the public one) | Off | On, off | Company; policy override | Same | scanning.sources.replace_defaults; controls.sources.overrides.replace_defaults |
| Allow git dependencies (policy editor: Git dependencies, Flag them / Allow them) | A dependency taken from a git repository is not a finding | Off | On, off | Company; policy override | Same | scanning.sources.allow_git; controls.sources.overrides.allow_git |
| Allow URL dependencies (policy editor: URL dependencies) | A dependency downloaded from an archive URL is not a finding | Off | On, off | Company; policy override | Same | scanning.sources.allow_url; controls.sources.overrides.allow_url |
| Allow local path dependencies (policy editor: Local path dependencies) | A dependency taken from a local path or link is not a finding, nor is a --find-links to a local directory | Off | On, off | Company; policy override | Same | scanning.sources.allow_path; controls.sources.overrides.allow_path |
| Packages left out | The check does not look at where these packages come from | Empty | Package names, one per line (policy editor: separated by commas), * wildcards (@corp/*), matching ignores case; no spaces | Company; policy override | Same | scanning.sources.allowed_packages; controls.sources.overrides.allowed_packages |
Notes:
- A policy's Registries list replaces the company's registries as a whole (all ecosystems); the policy's own Packages left out list (even empty) replaces the company's list.
- An ecosystem other than the five above, or an entry that is not a host,
host:portorhost/path, is refused when it is saved (Each line must be a host, host:port or host/path, without credentials, a query or wildcards.). - Packages left out applies to package entries; it does not silence
lockfile-missing-updateor the pip index options. - Settings take effect at the next scan (a new commit or a re-scan).
What the control says
| Status | Message |
|---|---|
| Pending | Checking where new dependencies come from. |
| Passed | New dependencies come from allowed sources. (with N entr(ies) of a form Merge Pilot cannot tell the source of; review them. when there are informational findings) |
| Failed | N dependency source finding(s) (rule count, …)., such as 2 dependency source finding(s) (registry-not-allowed 1, source-git 1). |
| Failed | The dependency source check could not be completed: … Fix the cause and rescan. |
| Failed | The dependency scan could not be completed: … Fix the cause and rescan. |
When it runs
With the dependency scan: once per commit when the policy runs the dependency scan, licenses, package health or dependency sources; on Re-scan dependencies on the merge request page (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 Dependency sources section: New dependencies come from allowed sources., Could not be checked: …, or each finding with its label, package, host,
file:lineand explanation. The first 100 findings are kept on the merge request (failing ones first; Showing N of M. when there are more); the full scan result keeps up to 5,000. - The Merge Pilot: Dependency Scan comment in the VCS gets a Dependency sources section: the number of findings (and how many are to review (source form not known)) and a table of rule, package, host, file and finding, or could not be checked: ….
- Policy card and status comment: the Dependency sources line.
- My Work: a merge request held by this control is listed with the reason Dependency sources failed (
sources_blocked). See My Work.
GitLab and GitHub
The check is the same on both.
Audit log
| Action | When |
|---|---|
dependency_sources_detected | The check found dependency source findings, informational ones included (written again when their number changes). Details: the repository, the merge request number, the findings that fail the check, the informational ones, the count per rule and the files checked |
sca_rescan | Someone started the dependency scan again |
See Audit log.
API fields
| Where | Field | Meaning |
|---|---|---|
| Policy | controls.sources.mode | off, report or block |
| Policy | controls.sources.overrides | registries, replace_defaults, allow_git, allow_url, allow_path, allowed_packages; absent or null: the company's |
| Company | scanning.sources | The same fields, the company defaults |
| Merge request | sca_scan.sources.status | clean (nothing that fails the check; informational findings may be listed), findings or failed |
| Merge request | sca_scan.sources.count, .informational, .by_rule | The findings that fail the check, the informational ones, and the count per rule |
| Merge request | sca_scan.sources.findings[] | file, line, package, version, ecosystem, rule, host, url, message |
| Merge request | sca_scan.sources.files_checked, .error | The dependency files read; why the check could not be completed |
| Scan result | source_findings[] | Every finding of the scan (up to 5,000), from GET /api/v1/companies/{id}/sca-results/{resultId} |
| Merge request | decision.controls[] with control: "sources" | The control's status, blocking and reason |
Related pages
- Dependency scan: the scan this check runs in, its supported files, path filters and failure setting.
- Package health and Licenses: the other checks of the same scan.
- CI configuration check: pinning in CI configuration.
- Troubleshooting scans: false positives and private registries.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →