Controls
Controls are the checks a change policy runs on each merge request it covers: work items, code review, CI, scans, risk and the change approval. Each policy chooses which controls apply and how strictly, so a production release can be held for a failed scan while a documentation change only reports it. Controls are set on the policy editor's Checks tab (What a covered merge request must pass. Report shows the result on the merge request; Enforce also holds the merge until it passes.), and on its Approval tab for the change approval.
The controls
| Control (label in the UI) | What it checks | Default for a new policy | API field |
|---|---|---|---|
| Work items | A tracker issue key, such as PAY-123, referenced by the change | Off | controls.work_items |
| Code review | Approving reviews on the latest commit in the VCS | Off | controls.code_review |
| CI | Pipelines or checks on the latest commit, from the sources the policy trusts | Off | controls.ci |
| Secret scan | Credentials, keys and tokens added by the change | Off | controls.secret_scan |
| Dependency scan | Known vulnerabilities in dependencies the change adds or upgrades | Off | controls.sca |
| Licenses | Licenses of the dependencies the change adds or upgrades | Report | controls.licenses |
| Package health | New dependency versions published only days ago, or deprecated by their registry | Report | controls.package_health |
| Dependency sources | Where new and changed dependencies come from: lockfiles left behind, registries that are not allowed, git, URL and local path dependencies, pip index options | Report | controls.sources |
| CI configuration check | Changed GitHub Actions workflows and GitLab CI configuration | Off | controls.workflows |
| Container image scan | Known vulnerabilities in the container images a change starts referring to | Off | controls.images |
| Infrastructure check | Misconfigurations a change introduces in Terraform, Kubernetes, Helm, Dockerfile, CloudFormation and Azure ARM files | Off | controls.iac |
| Signed commits | Every commit of the change carries a signature the VCS verified | Off | controls.signatures |
| Risk | The change's risk score, from the company's risk settings, and from which level it holds the merge | The company's setting | controls.risk |
| Change approval | The change approval the change type asks for, and who must approve it | Follows the change type | controls.approval |
Two more lines can appear in a merge request's checklist without being set in the policy:
- Change freeze: during a company change freeze (the company's Change calendar), merges are held. A freeze either holds every merge, or lets only emergency changes merge; an emergency change then passes this line, and the Risk control does not hold it for the critical level that freeze raised (see Risk). It is never set per policy.
- Policy: shown only when the policy refuses the merge request; it blocks it (see Change types).
Licenses, package health and dependency sources default to Report, also in every template and for a policy created through the API without them; the other controls default to Off.
Control modes
Each control on the Checks tab, except Risk, has three modes:
| Mode (label in the UI) | What it does | Merge gate | Status comment and checklist | API value |
|---|---|---|---|---|
| Off | The control is not checked: no scan is started for it | Not affected | Not shown | off |
| Report | The control runs and its result is shown on the merge request | Never held: a failure or a pending result does not hold the merge | Shown; a failure is marked as a warning (⚠️ in the status comment, (report only) in Merge Pilot) | report |
| Enforce | The control runs and holds the merge until it passes | A failure blocks the merge; a pending result keeps it waiting | Shown; a failure is marked as failing (❌) | block |
For Work items, the API values are off, record (Report: the work items found are linked, a change without one still passes) and required (Enforce).
For Risk, the policy chooses a threshold instead of a mode: Company setting (…), Never hold, or Hold at low and above to Hold at critical and above (see Risk).
The editor's Checks tab shows how many controls are enforced (3 enforced), and the policy list shows a chip for each control that is on, such as CI must pass (enforced) or CI (report).
What the merge gate shows
After each evaluation Merge Pilot sets the merge gate for the merge request's latest commit:
| Gate (label in Merge Pilot) | When |
|---|---|
| Blocked | At least one enforced control failed |
| Waiting | No enforced control failed, but at least one is still pending (a scan running, CI not finished, the change approval not yet approved) |
| Can merge | Every enforced control passed |
The gate's title names the first enforced control that failed, or the first one still pending, with its reason, such as CI: Failed: build. When all pass it reads Approved by change management. Report-mode controls never change the gate. What the gate is in each VCS is described in Core concepts.
The status comment
Merge Pilot keeps one comment on the merge request up to date, editing it in place instead of adding new ones:
- a headline: this merge request can merge., this merge request is waiting on the items below. or this merge request cannot merge yet. (for a policy that refuses its changes: this merge request cannot merge: its policy refuses it.);
- the policy, its version and the change type, such as Policy Normal changes (v4, normal change), or (v1, refuses its changes) for a Refuse policy;
- one line per control that applies (controls that are off or skipped are left out), in this order: Work items, Code review, CI, Secret scan, CI configuration check, Signed commits, Dependency scan, Licenses, Package health, Dependency sources, Container image scan, Infrastructure check, Risk, Change freeze, Change approval. Each line is marked ✅ passed, ⏳ pending, ❌ failed (enforced) or ⚠️ failed (report only), with the reason;
- when it was updated and for which commit.
For a watched repository nothing is written to the VCS: no merge gate, no comment. The decision is recorded in Merge Pilot as what change management would have done (Would pass (watched), Would wait (watched), Would be blocked (watched)).
Controls that are skipped
A control that is on can still be left out of the decision:
- the scans (secret scan, dependency scan, licenses, package health, dependency sources, CI configuration check, container image scan, infrastructure check, signed commits) on a watched repository whose company does not scan watched merge requests: Not scanned: scans are off for watched repositories.
- Code review when it asks for no approving review and does not hold on requested changes;
- Risk when the company's risk assessment is off: Risk assessment is off for this company.
- Work items in Report mode when the project has no tracker.
Company settings and policy overrides
The scans follow the company's scan settings (the company's Scanning tab). A policy can take over some of them for the merge requests it covers. When a scan control is not Off, the editor shows those settings in a box (These follow the company's scan settings unless chosen here., with a link to the company scan settings):
- a choice offers Company setting (…) (with the company's current value in brackets) or one of its values. Company setting keeps following the company, also when the company's value changes later;
- a list offers Company setting (…) or This policy's list. A policy's own list replaces the company's list, and an empty list is a real choice (for example, no exempt authors).
| Control | Settings a policy can take over in the editor | API field (under controls.<control>.overrides) |
|---|---|---|
| Secret scan | Files the VCS sends no diff for, "gitleaks:allow" comments, When the scan cannot finish, Lowest severity that holds the merge, Commit messages and description | unscanned_files, inline_allow, on_error, min_severity, scan_texts (the API also takes custom_rules_enabled, allowed_paths, allowed_rules) |
| Dependency scan | When the scan cannot finish; in Enforce mode also Vulnerabilities without a rating, Vulnerabilities exploited in the wild (CISA KEV), Hold from exploitation likelihood (EPSS) | on_error, unknown_severity, kev, epss_hold (the API also takes allowed_paths, blocked_paths) |
| Licenses | Denied licenses, Allowed licenses, Only allowed licenses; in Enforce mode also Licenses that cannot be checked | denied, allowed, allow_list_only, unknown |
| Package health | Minimum version age, Deprecated versions | min_age_days, deprecated |
| Dependency sources | Registries, Public registries, Git dependencies, URL dependencies, Local path dependencies, Packages left out | registries, replace_defaults, allow_git, allow_url, allow_path, allowed_packages |
| CI configuration check | Actions that need not be pinned, GitLab includes that need not be pinned, Images allowed without a digest | pin_allowed, include_allowed, image_allowed |
| Container image scan | Vulnerabilities without a fix, Image references that cannot be resolved, Vulnerabilities without a rating, Images not scanned | block_unfixed, unresolved, unknown_severity, skipped_images |
| Infrastructure check | File types checked, Changed files that cannot be checked, Checks left out, Files not checked | types, unchecked, skipped_checks, skipped_paths |
| Signed commits | Authors that need not sign | exempt_authors |
A setting left out of overrides (or null) follows the company. What each setting does is on the control's own page.
Below the scan rows, the box When a scan cannot see everything (For the dependency, license, package health, source, CI configuration, image and infrastructure scans, and the risk of a change.) takes over the company's choices of the same name, each with Company setting (…) or one of its values (see Scanning):
| Setting (label in the UI) | Choices | API field (under controls.coverage) |
|---|---|---|
| The VCS lists only part of the changed files | The scans fail, Check what was listed, say what was not | incomplete (fail, note) |
| More than the limits | The scans fail, Check the first ones, name the rest | over_limit (fail, note) |
| An image, infrastructure or CI configuration scan could not complete | Fail, rescan by hand, Fail, retry automatically | on_error (manual, retry) |
| Risk of a change listed only in part | Unknown: held wherever risk holds, or Count it as low risk, … medium risk, … high risk, … critical risk | unreadable_risk (hold, low, medium, high, critical) |
A field left out of controls.coverage follows the company. When a scan passes only because these choices let it, its line on the merge request ends with Not looked at: …, naming what it did not check.
Other company settings work alongside the policy in the same way:
- Risk: the policy's Company setting follows the company's risk settings (the company's Risk tab); the policy can instead never hold, or hold from its own level.
- When nobody can be assigned a change approval: The company's setting or the policy's own choice (see Change approval).
- Who may declare an emergency: the company's emergency rules, or the policy's own (see Who may declare an emergency).
The control modes themselves (Off, Report, Enforce) have no company default: each policy sets its own.
When controls run
Merge Pilot evaluates a merge request again whenever something it depends on changes. The work is done by background jobs (see Jobs):
- The merge request changes: opened, reopened, new commits pushed, its target branch changed, its title or description edited, its labels or draft state changed. The policy is matched again, the scans the policy runs are started for the new latest commit, risk is assessed, work items are looked up, and the merge request is evaluated.
- A result arrives: a scan or CI run finishes, a code review is given, a vote is cast or the change approval is decided in the tracker, someone accepts a risk, a vulnerability exception changes. The merge request is evaluated again with the new result.
- The policies change: every open merge request of the VCS connection is evaluated again (see Open merge requests after a change).
- The periodic re-check of open merge requests catches events whose webhook was lost.
Scans and new commits
- Every decision is for the merge request's latest commit. A new commit starts the policy's scans again and sets every result back to pending for that commit; CI, reviews and signatures are read for the new commit too.
- A scan runs once per commit. It does not run again for the same commit unless:
- someone selects Re-scan on the merge request (also Re-scan dependencies and Check the CI configuration again);
- it failed and the company (or the policy) says Fail, retry automatically under When the scan cannot finish (secret and dependency scans) or An image, infrastructure or CI configuration scan could not complete (those three scans; a scan failed by a limit or a cut-short file list is never retried): it is started again when the merge request is next processed after a pause (10 minutes by default). With Fail, rescan by hand, it stays failed until a re-scan;
- the policy now runs a check the finished dependency scan did not include (for example Licenses was turned on): the dependency scan runs again.
- One dependency scan serves the Dependency scan, Licenses, Package health and Dependency sources controls: it runs when any of the four is on.
- While a scan is pending, an enforced scan control keeps the merge waiting.
- What a new commit does to an existing change approval is the policy's New commits after a change approval setting (see Change policies).
The change approval waits for some controls
A normal change's change approval is opened only once the change is acceptable for review: its enforced work items check out and no risk hold applies. Until then the Change approval line says so, while CI and scans can already run. See Change approval.
Related pages
- Change policies: change types, the list and the testers.
- Matching: which merge requests a policy covers.
- Jobs:
mr_process,mr_evaluateand the scan jobs.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →