Scanning
The company's Scanning tab holds the company defaults of every scan Merge Pilot runs on merge requests, and the settings of the vulnerability inventory that follows each project's default branch. Company defaults for the scans; whether a merge request is scanned, and whether a finding holds it, is set per change policy.
A scan runs only where a change policy turns its control on (Report or Enforce); see Controls. Some of the settings below can be taken over by a policy for the changes it covers (Company settings and policy overrides).
Where to find it
Administration → Company (platform admins: Administration → Companies → the company), tab Scanning. The company page opens for company admins and platform admins only.
The tab has seven sections, chosen with the buttons at the top: Secrets, Dependencies, CI configuration, Container images, Infrastructure, Commits and When a scan cannot see everything.
The settings are saved with Save changes in the bar at the bottom of the company page, together with the other tabs (PUT /api/v1/companies/{id}): the scan settings as the scanning object, the vulnerability inventory settings as the vulnerabilities object. Each object is saved as a whole: a field left out takes its default.
Whether watched repositories are scanned at all is set on the Repositories tab (Scan watched merge requests for secrets, vulnerable dependencies and licenses); see Repositories settings.
File patterns on this tab are read the same way everywhere: One per line. A pattern without "/" matches a file or folder name anywhere ("*.test.go", "testdata"); one with "/" is read from the repository root ("docs/**", "/scripts"). "**" spans folders.
Secrets
The company defaults of the Secret scan control. Every field is documented in Secret scan → Settings.
| Card | Settings |
|---|---|
| Detection settings | Enable custom detection rules, Max findings per scan (default 50), External call timeout (seconds) (default 30) |
| Behaviour | Files the VCS sends no diff for, "gitleaks:allow" comments, When the scan cannot finish, Lowest severity that holds a merge (default Low (every finding): findings below it are listed on the merge request but do not hold it), Scan commit messages and the merge request description, Decoding depth (default 5) |
| Allowed paths | Files that are not scanned |
| Allowed rules | Rules that are not run, listed as Custom rules (mp-) and built-in rules, with a search and Select all / Deselect all. Custom rules can be ticked only while Enable custom detection rules is on |
API: scanning.secrets.
Dependencies
Six cards: Dependency vulnerability scanning, Vulnerability tracking, Path filters, Licenses, Package health and Dependency sources.
Dependency vulnerability scanning
Scan merge request dependencies for known vulnerabilities using OSV.dev. The company defaults of the Dependency scan control: Vulnerabilities without a rating, When the scan cannot finish, Vulnerabilities exploited in the wild (CISA KEV), Hold from exploitation likelihood (EPSS, %), Max dependencies per scan, Max vulnerabilities stored and External call timeout (seconds) are documented in Dependency scan → Settings.
Two more fields on this card do not affect merge requests. They bound the project analysis (Run analysis on a project's Security tab, and the analyses run after a merge or a direct change touches a dependency manifest of the default branch) and the advisory check of the vulnerability inventory (below):
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Max dependencies per project analysis | How many dependencies one project analysis, and one advisory check, looks up. The number is shared evenly among the project's manifests. An analysis that finds more checks only this many and is marked incomplete (max_deps_exceeded, with the number of dependencies not checked) | 20,000 | 0 to 20,000 (0: the default) | Company | Company admins, platform admins | scanning.sca.analysis_max_dependencies |
| Project analysis timeout (seconds) | How long each lookup of a project analysis and of the advisory check may take (vulnerability and license lookups). They ask about many more packages than a merge request's scan | 90 | 0 to 600 (0: the default) | Company | Company admins, platform admins | scanning.sca.analysis_timeout_seconds |
Vulnerability tracking
Each registered project's default branch has a vulnerability inventory (Insights → Vulnerabilities): what affects it, since when, and which merge request brought it in. The inventory of a project starts with its first project analysis; this card sets how it is kept up to date and how long its history is kept.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Update it when a merge request that changes a dependency manifest, a file that refers to container images or an infrastructure file merges | After a merge into the default branch that changed such a file (image and infrastructure files only while their inventory below is on), the project's default branch is analysed again (job vuln_refresh), and new findings are attributed to that merge request. Imported past merge requests never start one | On | On, off | Company | Company admins, platform admins | vulnerabilities.analyse_on_merge |
| Follow the container images the default branches refer to | Each analysis and advisory check scans the images in Dockerfiles, Kubernetes manifests, Helm values and Compose files. Their vulnerable packages are findings in the inventory (see Vulnerability inventory), whether or not a policy runs the container image scan on merge requests. Turned off and saved, the image findings (open and fixed: that inventory's history) and what was read of the images are deleted (audit vulnerability_inventory_cleared), and analyses, advisory checks, merges and direct changes no longer scan images. Turned on again, the next analysis starts a new baseline: what it finds is not announced | On | On, off | Company | Company admins, platform admins | vulnerabilities.image_inventory |
| Follow the default branches' infrastructure files | Each analysis checks Terraform, Dockerfiles, Kubernetes and Helm files for misconfigurations. They are kept as infrastructure findings, whether or not a policy runs the infrastructure check on merge requests. Turned off and saved, the infrastructure findings (open and fixed) and what was read of the files are deleted (audit vulnerability_inventory_cleared), and analyses, merges and direct changes no longer check them. Turned on again, the next analysis starts a new baseline | On | On, off | Company | Company admins, platform admins | vulnerabilities.iac_inventory |
| Check the dependencies in use for new advisories every (hours) | Without reading the repositories: only the advisory database is asked. Each project with a known dependency list has its dependencies looked up again when its last check is older than this; a new advisory for a version in use becomes a finding. 0 turns it off | 24 | 0 to 720 | Company | Company admins, platform admins | vulnerabilities.advisory_check_hours |
| Longest exception (days) | An accepted or not-affected vulnerability is held for review again after at most this many days. A vulnerability exception (on the Vulnerabilities page) cannot end later than the end of the day that is this many days from today, in the company's time zone (an exception lasts at most N days: the latest expiry is the end of <date> (<time zone>)); when it ends, the vulnerability counts again | 90 | 1 to 730 (API: 0 takes the default) | Company | Company admins, platform admins | vulnerabilities.exception_max_days |
| Keep fixed vulnerabilities, old analyses and direct changes (days) | Once a day, fixed vulnerabilities, ended or revoked exceptions and the details of older analyses (their summaries stay; the latest completed analysis of each project keeps its details, the SBOM's source) are deleted after this many days. Open and accepted vulnerabilities are always kept. Direct changes older than this are removed too. See How long direct changes are kept | 365 | 30 to 3,650 (API: 0 takes the default) | Company | Company admins, platform admins | vulnerabilities.retention_days |
The advisory check runs in the background, at most 200 projects per company per round, the oldest checked first. It does not run for an inactive company; that company's exceptions still expire. It needs no VCS calls. When a lookup fails, nothing is concluded and the next round tries again.
Who is told about new vulnerabilities on default branches is set on the company's Notifications tab, What is announced → New vulnerabilities on default branches: Critical only, High and above (the default), Medium and above, Low and above, Every severity, unrated too or Never (API vulnerabilities.notify_min_severity: critical, high, medium, low, unknown, none). They are announced as the vulnerability_found event: one message for each round of checks, naming the projects and the worst findings first, linked to the vulnerability inventory (see Events).
A direct change to a dependency manifest on the default branch can also refresh the inventory: see Refresh the vulnerability inventory when one changes a dependency manifest in Repositories settings.
Path filters
Allowed paths and Blocked paths: which dependency manifests the dependency scan reads. See Dependency scan → Settings. API: scanning.sca.allowed_paths, scanning.sca.blocked_paths.
Licenses
Denied licenses, Allow only the licenses below, Allowed licenses and Licenses that cannot be checked: the company defaults of the Licenses control. See Licenses → Settings. API: scanning.licenses.
Package health
Minimum version age (days) and Flag deprecated versions: the company defaults of the Package health control. See Package health → Settings. API: scanning.packages.
Dependency sources
Where the dependencies a change adds may come from: the registries allowed per ecosystem, and whether git, URL and local path dependencies are allowed. Checked in the dependency scan when a policy turns dependency sources on. The company defaults of the Dependency sources control:
- Private registries: one list per ecosystem (npm registries, PyPI registries, crates.io registries, RubyGems registries, Packagist registries), each showing the public registries allowed by default. Add the registries your package managers use besides the public ones: a host,
host:portorhost/pathper line. - Only the listed registries: the public registries are not allowed either, in every ecosystem.
- Allow git dependencies, Allow URL dependencies, Allow local path dependencies (all off by default).
- Packages left out: package names,
*wildcards, whose sources are not checked.
See Dependency sources → Settings. API: scanning.sources.
CI configuration
Card CI configuration: What the CI configuration check (a policy control) accepts in changed GitHub Actions workflows and GitLab CI configuration. Three settings: Actions that need not be pinned (GitHub; default actions/* and github/*), GitLab includes that need not be pinned (empty by default) and Images allowed without a digest (GitLab; empty by default). See CI configuration check → Company default. API: scanning.workflows.
Container images
Card Container images: what the container image scan (a policy control) does with the images a change starts referring to. Settings: Hold for vulnerabilities without a fix (off by default), Image references that cannot be resolved (Fail the scan by default, or List only), Vulnerabilities without a rating (Listed, never held by default, Count them as high, or Always hold), Images not scanned, Platform (linux/amd64), Max new images per change (20) and Internal hosts. See Container image scan → Company default. API: scanning.images.
Container registries
Card Container registries: the sign-ins the container image scan uses to pull images from private registries. Public images need none. Add registry adds one:
| Field (label in the UI) | What it is |
|---|---|
| Name | A name for the registry |
| Host | The registry's address, host or host:port, no path: ghcr.io, registry.gitlab.example.com, 123456789012.dkr.ecr.eu-west-1.amazonaws.com, europe-docker.pkg.dev, docker.io (Docker Hub, under any of its names). One sign-in per host |
| Sign-in | User name and password or token; Amazon ECR (access key): an access key ID and secret access key, turned into an ECR token for each scan, with an optional Region (taken from the host when empty); Google Artifact Registry (service account key): a service account key (JSON), turned into an access token for each scan |
| CA certificate | A PEM certificate trusted besides the system CAs, for a registry with a private CA |
| Skip TLS verification | The registry's certificate is not checked. Prefer adding its CA certificate |
Use a token that can only read the registry: on GitLab a deploy token or access token with read_registry, on GitHub a token with read:packages, on Google a service account with Artifact Registry Reader. The password, key or token is stored encrypted and never shown again (Configured); it is kept when the field is left empty, as long as the host, sign-in kind and user name stay the same: a stored secret is never sent to another registry. Test signs in to the registry as a scan would and says whether it worked (audited as registry_test). A sign-in is used for its own registry only.
API: registries in PUT /api/v1/companies/{id} (the list replaces the stored one); POST /api/v1/companies/{id}/test-registry tests one.
Infrastructure
Card Infrastructure: what the infrastructure check (a policy control) looks at. Settings: File types checked (all by default), Changed files that cannot be checked (Fail the check by default, or List only), Checks left out, Files not checked and Max infrastructure files per change (50). See Infrastructure check → Company default. API: scanning.iac.
When a scan cannot see everything
Section When a scan cannot see everything: what the dependency, license, package health, source, CI configuration, image and infrastructure scans do when they cannot look at all of a change. The secret scan has its own choices (Behaviour card). A policy can set its own for each.
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| The VCS lists only part of the changed files | A change too large for the VCS to list whole. The scans fail: held wherever a scan holds; a rescan does not change it, so it is not retried by itself. Check what was listed and say what was not: the scans check the files the VCS listed and say that others may have been missed | The scans fail | fail, note | scanning.coverage.incomplete |
| More images, infrastructure files or dependencies than the limits | The scan fails (not retried by itself). Check the first ones up to the limit and say how many were left out. Also covers the image scan's limit of 100 files that may name images and the CI configuration check's limit of 50 changed CI configuration files | The scan fails | fail, note | scanning.coverage.over_limit |
| An image, infrastructure or CI configuration scan could not complete | Wait for a rescan, or Try again after a pause. A scan failed by a limit or a cut-short file list is never retried | Wait for a rescan | manual, retry | scanning.coverage.on_error |
| Risk of a change the VCS listed only in part | Its size and paths are not fully known. Unknown: held wherever risk holds, or counted as a risk level (low, medium, high, critical). The merge request says which. During a change freeze that raises the risk, the change stays critical whatever is chosen here | Unknown | hold, low, medium, high, critical | scanning.coverage.unreadable_risk |
The dependency source check follows The VCS lists only part of the changed files and More … than the limits as the dependency scan does. A scan failed only by a cut-short file list or a limit says Trying again would not change this: change the merge request or the company's scan settings, then use rescan, instead of saying that Merge Pilot tries again. With Check what was listed or Check the first ones up to the limit, what the scan left out is named in the control's reason (Not looked at: …).
Commits
Card Signed commits: Who the signed-commits check (a policy control) leaves out. One setting, Authors that need not sign (empty by default). See Signed commits → Company default. API: scanning.signatures.exempt_authors.
Validation
Saving is refused, with the reason, when:
- a limit or timeout is negative or above its maximum (… must be between 0 (the default) and …);
- Decoding depth is not 0 to 10, or Minimum version age (days) not 0 to 365;
- a license entry is not an SPDX license id, or an allowed license uses a wildcard;
- an Actions that need not be pinned entry is not
owner/*orowner/repo, a GitLab includes that need not be pinned entry has no/or holds a space or@, or an Images allowed without a digest entry is empty or holds a space; - a registry entry is not a host,
host:portorhost/path(Each line must be a host, host:port or host/path, without credentials, a query or wildcards.), or a Packages left out entry holds a space; - a file pattern is not valid;
- Platform is not
os/archoros/arch/variant, an Internal hosts entry is not a host orhost:port, Max new images per change is not 0 to 100 or Max infrastructure files per change not 0 to 500; - a container registry has no name or host, a host with a path, a host another registry already has, no user name or access key ID where its sign-in needs one, a CA certificate that is not PEM, or no password, key or token (also when its host, sign-in kind or user name changed: the stored one is not kept then);
- Check the dependencies in use for new advisories every (hours) is not 0 to 720, Longest exception (days) not 1 to 730, or Keep fixed vulnerabilities, old analyses and direct changes (days) not 30 to 3,650.
When changes take effect
- Scan settings: at the next scan of a merge request (a new commit or a re-scan); a few are applied at the next evaluation without a new scan. Each control's page says which.
- Max dependencies per project analysis and Project analysis timeout (seconds): at the next project analysis or advisory check.
- Check the dependencies in use for new advisories every (hours): at the next round of the background check.
- Longest exception (days): for exceptions made afterwards; existing exceptions keep their end date.
- Keep fixed vulnerabilities, old analyses and direct changes (days): at the next daily clean-up.
API fields
| Field | Values |
|---|---|
scanning.secrets | See Secret scan |
scanning.sca | See Dependency scan; also analysis_max_dependencies (0 to 20,000) and analysis_timeout_seconds (0 to 600) |
scanning.licenses | See Licenses |
scanning.packages | See Package health |
scanning.sources | registries, replace_defaults, allow_git, allow_url, allow_path, allowed_packages. See Dependency sources |
scanning.workflows | pin_allowed, include_allowed, image_allowed. See CI configuration check |
scanning.coverage | incomplete, over_limit (fail, note), on_error (manual, retry), unreadable_risk (hold, low, medium, high, critical). See When a scan cannot see everything |
scanning.images | block_unfixed, unresolved (fail, note), unknown_severity (show, high, block), skipped_images, platform, max_images (0 to 100), internal_hosts. See Container image scan |
scanning.iac | types, unchecked (fail, note), skipped_checks, skipped_paths, max_files (0 to 500). See Infrastructure check |
registries | See Container registries |
scanning.signatures.exempt_authors | See Signed commits |
vulnerabilities.analyse_on_merge | true (default), false |
vulnerabilities.image_inventory, vulnerabilities.iac_inventory | true (default), false |
vulnerabilities.advisory_check_hours | 0 to 720 (default 24; 0: off) |
vulnerabilities.notify_min_severity | critical, high (default), medium, low, unknown, none |
vulnerabilities.exception_max_days | 1 to 730 (default 90) |
vulnerabilities.retention_days | 30 to 3,650 (default 365) |
Related pages
- Controls: control modes and policy overrides.
- Secret scan, Dependency scan, Licenses, Package health, Dependency sources, CI configuration check, Container image scan, Infrastructure check, Signed commits.
- Repositories settings: scans of watched repositories, direct changes.
- Jobs:
project_analysisandvuln_refresh. - Company overview.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →