Skip to main content
4 video tutorials

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 checksDefault for a new policyAPI field
Work itemsA tracker issue key, such as PAY-123, referenced by the changeOffcontrols.work_items
Code reviewApproving reviews on the latest commit in the VCSOffcontrols.code_review
CIPipelines or checks on the latest commit, from the sources the policy trustsOffcontrols.ci
Secret scanCredentials, keys and tokens added by the changeOffcontrols.secret_scan
Dependency scanKnown vulnerabilities in dependencies the change adds or upgradesOffcontrols.sca
LicensesLicenses of the dependencies the change adds or upgradesReportcontrols.licenses
Package healthNew dependency versions published only days ago, or deprecated by their registryReportcontrols.package_health
Dependency sourcesWhere new and changed dependencies come from: lockfiles left behind, registries that are not allowed, git, URL and local path dependencies, pip index optionsReportcontrols.sources
CI configuration checkChanged GitHub Actions workflows and GitLab CI configurationOffcontrols.workflows
Container image scanKnown vulnerabilities in the container images a change starts referring toOffcontrols.images
Infrastructure checkMisconfigurations a change introduces in Terraform, Kubernetes, Helm, Dockerfile, CloudFormation and Azure ARM filesOffcontrols.iac
Signed commitsEvery commit of the change carries a signature the VCS verifiedOffcontrols.signatures
RiskThe change's risk score, from the company's risk settings, and from which level it holds the mergeThe company's settingcontrols.risk
Change approvalThe change approval the change type asks for, and who must approve itFollows the change typecontrols.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 doesMerge gateStatus comment and checklistAPI value
OffThe control is not checked: no scan is started for itNot affectedNot shownoff
ReportThe control runs and its result is shown on the merge requestNever held: a failure or a pending result does not hold the mergeShown; a failure is marked as a warning (⚠️ in the status comment, (report only) in Merge Pilot)report
EnforceThe control runs and holds the merge until it passesA failure blocks the merge; a pending result keeps it waitingShown; 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
BlockedAt least one enforced control failed
WaitingNo enforced control failed, but at least one is still pending (a scan running, CI not finished, the change approval not yet approved)
Can mergeEvery 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).
ControlSettings a policy can take over in the editorAPI field (under controls.<control>.overrides)
Secret scanFiles the VCS sends no diff for, "gitleaks:allow" comments, When the scan cannot finish, Lowest severity that holds the merge, Commit messages and descriptionunscanned_files, inline_allow, on_error, min_severity, scan_texts (the API also takes custom_rules_enabled, allowed_paths, allowed_rules)
Dependency scanWhen 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)
LicensesDenied licenses, Allowed licenses, Only allowed licenses; in Enforce mode also Licenses that cannot be checkeddenied, allowed, allow_list_only, unknown
Package healthMinimum version age, Deprecated versionsmin_age_days, deprecated
Dependency sourcesRegistries, Public registries, Git dependencies, URL dependencies, Local path dependencies, Packages left outregistries, replace_defaults, allow_git, allow_url, allow_path, allowed_packages
CI configuration checkActions that need not be pinned, GitLab includes that need not be pinned, Images allowed without a digestpin_allowed, include_allowed, image_allowed
Container image scanVulnerabilities without a fix, Image references that cannot be resolved, Vulnerabilities without a rating, Images not scannedblock_unfixed, unresolved, unknown_severity, skipped_images
Infrastructure checkFile types checked, Changed files that cannot be checked, Checks left out, Files not checkedtypes, unchecked, skipped_checks, skipped_paths
Signed commitsAuthors that need not signexempt_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)ChoicesAPI field (under controls.coverage)
The VCS lists only part of the changed filesThe scans fail, Check what was listed, say what was notincomplete (fail, note)
More than the limitsThe scans fail, Check the first ones, name the restover_limit (fail, note)
An image, infrastructure or CI configuration scan could not completeFail, rescan by hand, Fail, retry automaticallyon_error (manual, retry)
Risk of a change listed only in partUnknown: held wherever risk holds, or Count it as low risk, … medium risk, … high risk, … critical riskunreadable_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.

  • Change policies: change types, the list and the testers.
  • Matching: which merge requests a policy covers.
  • Jobs: mr_process, mr_evaluate and 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 →

Checks — Off, Report or EnforceYouTube ↗
Standard Changes — Pre-Approved, Still RecordedYouTube ↗
Emergency Changes — Merge Now, Review AfterYouTube ↗
Refuse Changes by PolicyYouTube ↗