Skip to main content
Video tutorial · 1:34

Risk

Every merge request gets a risk score from the company's risk settings: when the change is made, how critical the service is, what kind of files it touches and how large it is. The policy's Risk control decides from which risk level the score holds the merge until someone accepts the risk. Change freezes from the company's change calendar also act on the merge gate, through the Change freeze control.

For a short overview of what it is for, see the Risk & change calendar feature page.

Risk assessment is a company setting and is off by default. While it is off, no change gets a score and nothing is held for risk, whatever a policy says. Change freezes that hold merges work whether risk assessment is on or not.

How the risk is scored​

The score is between 0 and 1. It is the weighted sum of four factor scores, each between 0 and 1:

risk score = change window × its weight + service criticality × its weight + diff footprint × its weight + MR size × its weight

The result is kept between 0 and 1 and rounded to four decimals. With the default weights:

FactorDefault weightWhat it measures
Change window0.30When the change is assessed, against the company's change windows
Service criticality0.25The Service criticality of the policy that covers the change
Diff footprint0.25The riskiest kind of file the change touches
MR size0.20How many lines and files the change has

Levels​

The score gives the level:

LevelDefault: score at or above
Critical0.80
High0.60
Medium0.40
LowBelow the medium threshold

Two more cases:

  • Unknown: the changed files could not be read (the VCS sent only part of the list, or reading it failed), so the footprint and size cannot be scored. A change the VCS listed only in part stays unknown unless the company's Risk of a change the VCS listed only in part (or the policy's own choice) counts it as a level instead (see Scanning); the control then says The VCS listed only part of the change; it is counted as … risk, as the company chose. A change at unknown risk is held wherever the policy holds for risk, at any threshold, and needs the most approvals any risk level needs (see Approval).
  • During a change freeze (any freeze mode), every factor scores 1.0 and the change is critical. The merge request's risk card then says Blackout: Yes.

Change window​

Set on the company page, Change calendar tab, card Change windows. Times are in the company's Time zone (company General tab; UTC when it is not set).

  • No change windows: the factor scores 0.25 for every change.
  • Inside a window: the window's own Score (0.25 for a new window; 0 adds no timing risk).
  • Outside every window: the Out-of-window score (default 0.75).
  • A window covers the days ticked and the time from Start time up to, not including, End time, to the minute (09:30 to 17:15). A window whose end is before its start runs overnight: Friday 22:00 to 06:00 is Friday 22:00 to Saturday 06:00. An end of 00:00 is midnight at the end of the day.

The time used is the moment Merge Pilot assesses the change (when it processes the head commit, and again at each periodic re-check), not the moment it merges.

Service criticality​

Each policy can give the changes it covers a Service criticality (policy editor, Change type tab). The company maps each value to a score (Risk tab, card Criticality scores):

Service criticality of the policyDefault score
Critical1.0
High0.75
Medium0.5
Low0.25
None0.0
Not set0.1, always

Diff footprint​

Each changed file (and, for a renamed file, its old path) is compared with the footprint rules. The change takes the highest score of any matching rule, and that rule's category is shown on the merge request. Patterns work like .gitignore: a pattern without / matches a file or folder name anywhere (Dockerfile*, *.md); a pattern with / is matched from the repository root, and a folder covers everything inside it.

When the company sets its own rules, they replace the default rules entirely. The default rules:

CategoryPatternsScore
DB migration (db_migration)**/migration*, **/schema.*, **/seed*1.0
CI/CD (ci_cd).gitlab-ci.yml, .github/**, Jenkinsfile0.9
Infra (infra)**/deploy/**, **/helm/**, Dockerfile*, docker-compose*, values*.yaml, helmfile.yaml0.85
API (api)**/api/**, **/handler*, **/service*0.5
Frontend (frontend)**/frontend/**, *.tsx, *.jsx0.25
Tests (tests)*_test.*, **/__tests__/**, *.md, docs/**0.1

A file no rule matches scores 0.

Binary files. A change that adds or changes a file the VCS reports as binary gets a footprint of at least the Binary file footprint (default 0.8), with the category binary, because reviewers cannot read its content. Deleted binaries do not count. Set it to 0 to stop scoring binaries.

MR size​

MR size = churn score × churn weight + file count score × (1 − churn weight), with a churn weight of 0.80 by default.

  • Churn is added plus deleted lines. A binary file adds no lines. A file the VCS sent no diff and no line counts for (too large to show) counts as 1,001 added lines.
  • Files not counted in the size are left out of both churn and file count (they still count for the footprint). By default these are lockfiles, minified, generated and vendored code: package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, npm-shrinkwrap.json, go.sum, Cargo.lock, poetry.lock, Pipfile.lock, uv.lock, pdm.lock, Gemfile.lock, composer.lock, pubspec.lock, Podfile.lock, packages.lock.json, gradle.lockfile, mix.lock, *.min.js, *.min.css, *.pb.go, *_pb2.py, *.generated.*, *_generated.*, vendor, node_modules, dist.
  • Each count is scored by the highest threshold it reaches. When the company sets its own thresholds, they replace the defaults.
Churn (lines), at leastScoreChanged files, at leastScore
1,0011.0311.0
5010.75160.75
1010.560.5
510.2530.25
10.110.1

When the risk is assessed​

  • While risk assessment is on, every merge request is assessed when Merge Pilot processes a new head commit, whatever its policy.
  • The periodic re-check of open merge requests assesses them again. In companies with change windows, or with a change freeze in force, open merge requests are re-checked even when they could already merge, so a freeze or the end of a change window reaches them.
  • A level of an older commit is not used: until the head commit is assessed, the control shows Assessing the latest commit's risk. and does not hold the merge.
  • A new high or critical assessment of a head commit is announced (notification Risk assessed, mr_risk_assessed).

What the policy sets​

In the policy editor, Checks tab, row Risk.

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
RiskFrom which level the risk score holds the mergeCompany setting (…): the company's hold, shown in bracketsCompany setting: follow the company's Block on risk and Block threshold. Never hold: nothing is held for risk under this policy. Hold at low and above, Hold at medium and above, Hold at high and above, Hold at critical and above: hold from that level, even when the company does not block on riskPolicy override of the company defaultPolicy managers, company admins, platform adminscontrols.risk.block_threshold ("", never, low, medium, high, critical)
Who may lift a risk holdWho may accept the risk of a held change, with a reason. Not shown when nothing can be held under the policy (it never holds, or it follows a company that does not hold or has risk assessment off)The approvers (shown as The approvers when an approval requirement names an approver pool or asks the code owners, else Company administrators)The default, or one of the company's approver poolsPolicyPolicy managers, company admins, platform adminscontrols.risk.release_pool_id (null: the default)

When the company's risk assessment is off, the editor warns that nothing is held for risk whatever is chosen, with a link to the company's risk settings.

Choosing a release pool that is not one of the company's approver pools is refused when the policy is saved.

How the hold works​

The Risk control on the merge request:

StateShown asMerge gate
Risk assessment offNot shown (skipped)Not affected
The head commit not assessed yetAssessing the latest commit's risk.Not held
Below the hold level, or the policy never holdsRisk level medium. (the level)Not held
At or above the hold level (or unknown, where the policy holds)Risk level high. Changes at high risk or above are held until someone accepts the risk.Blocked
Held, and someone accepted the riskRisk level high. Accepted by …Passes

A risk hold also delays the change approval: it is opened (for an emergency change, the one for its review) only once no risk hold is in place (A change approval is opened once the work items check out and no risk hold applies; CI and scans can still run.). The hold applies to every change type, standard and emergency changes included, with one exception: during an Emergency changes only freeze, an emergency change is not held for the critical level the freeze raised (Risk level critical. Raised by change freeze …, which lets emergency changes through.).

Accepting a risk​

A held merge request has Allow risk on its Risk assessment card. It opens Lift the risk block?; the person gives a Justification of at least 10 characters and confirms with Lift risk block. The merge request is then evaluated again.

Who may accept:

The policy namesWho may accept
A release pool (Who may lift a risk hold)People of that pool who hold one of its repository roles on the change's repository (the project's approver roles when the pool names none)
No release pool, and its approval requirements name an approver pool or code ownersPeople who may approve the change under the policy (see Approval)
NeitherCompany administrators (and platform admins)

In every case:

  • The merge request's author never may.
  • The person must have linked their account on the merge request's VCS in My profile.
  • Auditors cannot accept a risk, and the button is not shown on watched repositories, where nothing is held.
  • The merge request must be open and still held.
  • The acceptance is for the head commit and the level the person saw. A new commit brings a new assessment that nobody has accepted, and so does a change of level for the same commit (for example when a freeze starts and the change becomes critical). Accepting an assessment that changed meanwhile is refused: reload and look again.

API: POST /api/v1/merge-requests/{id}/risk-allow with reason (at least 10 characters) and head_sha (the commit whose risk is accepted). It acts as a person: a session or a personal API token.

Change freezes​

Change freezes are periods set on the company's Change calendar tab, card Change freezes (Hold stops merges (approval can still go ahead); emergency only lets only emergency changes through; score only raises the risk to critical (every freeze does).). They act in two ways:

  1. On the risk score: while any freeze is in force, every change assessed scores critical (only while risk assessment is on).
  2. On the merge gate: the policy's Change freeze control holds merges during a freeze whose mode holds them, whether risk assessment is on or not.
Freeze mode (label in the UI)API valueMerge gateRisk score
Hold mergesholdEvery merge is held: Change freeze … until …: merges are held.Critical
Emergency changes onlyemergency_onlyChanges under an emergency policy pass (emergency changes may merge); every other change is heldCritical
Raise risk onlyscoreNot held by the freezeCritical; no effect while risk assessment is off
  • Times are wall-clock times in the company's time zone, from Start up to, not including, End. When several holding freezes overlap, Hold merges wins.
  • Scope. A freeze covers every repository, target branch and policy unless it is narrowed: Repositories (path patterns) (for example payments/*), Target branches (for example release/*) and Only changes under these policies. A change is covered when it matches every list that is set. A freeze that does not cover a change neither holds it nor raises its risk. When the merge's repository or policy cannot be read at merge time, every freeze counts for it.
  • Changes the VCS listed only in part. During a freeze that raises the risk, such a change stays critical: the level the company chose for them (Risk of a change the VCS listed only in part, see Scanning) does not lower the freeze's critical.
  • Exempt policies. A policy with Exempt from change freezes (policy editor, Checks tab) is never held by a freeze, nor is its risk raised by one.
  • Releasing one change. A policy with Let one held change go ahead during a freeze (off by default) lets someone release a held change: a member of the pool chosen in Who may release a change, else the policy's approvers, else a company administrator; never the author. On the merge request, Release from the freeze asks for a reason (10 characters at least) and releases the exact commit the person looked at: when the merge request has a newer commit meanwhile, the release is refused (the merge request has a newer commit (…): reload it and look at that one), and a newer commit is held again until released. The control then passes (… let this change go ahead (…)), a merge of the released commit is not recorded as made in the freeze, and the audit log gets freeze_release. A later commit merged after the release is recorded as merged in the freeze.
  • The Change freeze control has no mode in the policy: every policy applies it (a policy that refuses its changes is blocked anyway). It is shown only while a freeze holds merges.
  • A freeze holds the merge only. Approvals go on: the change approval can be opened and decided during the freeze.
  • Since a freeze makes every assessed change critical, a policy that holds for risk also holds changes during any freeze until someone accepts the risk. The exception is an emergency change during an Emergency changes only freeze: the freeze lets it through, and so does the risk control for the critical level that freeze raised. In Hold merges and Raise risk only freezes, emergency changes are held for risk like any other.
  • A merge during a freeze that holds it (in Emergency changes only, a merge of a change that is not under an emergency policy) is recorded as non-compliant: the merge request shows This change was merged during the change freeze "…", which held it. It is recorded as non-compliant., the audit log gets mr_merged_in_freeze, and the Merged during a change freeze notification is sent. In a watched repository nothing was held, so nothing is non-compliant: the merge request shows Would be blocked (watched): this change was merged during the change freeze "…", which would have held it under change management. (field would_have_held_in_freeze), without the audit entry or notification.
  • Open merge requests are re-checked periodically while a freeze is in force, so a gate opened before the freeze started is held again.
  • Saving the risk settings, freezes or windows (or approving that change under four-eyes review) has every open merge request of the company evaluated again at once, so ending a freeze early releases held changes without waiting for the re-check.

Company risk settings​

Risk tab and Change calendar tab of the company page. Both are saved with Save changes (PUT /api/v1/companies/{id} with the risk_config object). Company admins and platform admins change them. Auditors read them through the API (GET /api/v1/companies/{id}); the company page is for administrators. When the company has turned on four-eyes review (Governance tab), a change to Risk settings and change freezes waits until another administrator approves it. Every saved state of the risk settings is kept as a version.

Risk tab​

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Enable risk assessmentScores every merge requestOffOn, offCompanyCompany admins, platform adminsrisk_config.enabled
Block on riskHolds merge requests at or above the block threshold until the risk is accepted, under policies that follow the company settingOffOn, offCompany default (a policy can choose its own)Company admins, platform adminsrisk_config.block_on_risk
Block thresholdThe lowest level held. Shown when Block on risk is onHighLow, Medium, High, Critical (required when Block on risk is on)Company defaultCompany admins, platform adminsrisk_config.block_threshold
Change window weight, Service criticality weight, Diff footprint weight, MR size weightEach factor's share of the score0.30, 0.25, 0.25, 0.200 to 1 each; together they must add up to 1CompanyCompany admins, platform adminsrisk_config.weights.change_window, .service_criticality, .diff_footprint, .mr_size
Critical threshold, High threshold, Medium thresholdThe score from which a change has that level0.80, 0.60, 0.40Rising: 0 < medium < high < critical ≤ 1CompanyCompany admins, platform adminsrisk_config.level_thresholds.critical, .high, .medium
Criticality scores: Critical, High, Medium, Low, NoneThe score of each service criticality1.0, 0.75, 0.5, 0.25, 0.00 to 1 eachCompanyCompany admins, platform adminsrisk_config.criticality_scores.critical, .high, .medium, .low, .none
Footprint rules (File pattern, Category, Score)The company's own footprint rules; they replace the default rulesEmpty: the default rulesFile patterns; category DB migration, CI/CD, Infra, API, Frontend, Tests or Other; score 0 to 1CompanyCompany admins, platform adminsrisk_config.footprint_rules[] (pattern, category, score)
Binary file footprintThe lowest footprint of a change adding or changing a binary file0.80 to 1; 0 does not score binariesCompanyCompany admins, platform adminsrisk_config.binary_score
Churn weightThe share of churn in the MR size score; file count gets the rest0.800 to 1CompanyCompany admins, platform adminsrisk_config.size_churn_weight
Files not counted in the sizeFiles left out of churn and file count. Use the default list restores the defaultsThe default list aboveFile patterns; empty counts every fileCompanyCompany admins, platform adminsrisk_config.size_exclude (absent or null: the default list; []: none)
Churn thresholds (Min churn (lines), Score)Scores for line churn; they replace the defaultsEmpty: the defaults aboveMinimum 0 or more; score 0 to 1CompanyCompany admins, platform adminsrisk_config.size_thresholds[] (min_churn, score)
File count thresholds (Min files, Score)Scores for the number of changed files; they replace the defaultsEmpty: the defaults aboveMinimum 0 or more; score 0 to 1CompanyCompany admins, platform adminsrisk_config.file_thresholds[] (min_churn holds the file count, score)

The weights, thresholds and scoring cards are shown once Enable risk assessment is on.

Change calendar tab​

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Change freezes: Freeze name, Start, End, Freeze modeA period during which merges are held, or the risk raisedNone. A freeze added in the UI starts as Hold merges; one sent through the API without a mode is Raise risk onlyA name, required and unique; date and time (company time zone); End must be after Start; mode Hold merges, Emergency changes only, Raise risk only (any other mode is refused)CompanyCompany admins, platform adminsrisk_config.blackout_periods[] (name, start, end, mode: hold, emergency_only, score)
Freeze scope: Repositories (path patterns), Target branches, Only changes under these policiesNarrow a freeze to some repositories, branches or policiesEmpty: every oneGlob patterns (a regular expression is refused); policies of the company (another is refused)CompanyCompany admins, platform adminsrisk_config.blackout_periods[].projects, .branches, .policies
Change windows: Window name, days, Start time, End time, ScoreThe times changes are expected, and the timing score inside eachNone. A window added in the UI starts as 09:00 to 17:00 with score 0.25Days Sunday to Saturday (API 0 to 6, 0 is Sunday); times to the minute (API minutes from midnight: start 0 to 1439, end 0 to 1440, 1440 is midnight), the end not equal to the start; score 0 to 1CompanyCompany admins, platform adminsrisk_config.change_windows[] (name, day_of_week, start_minute, end_minute, score)
Out-of-window scoreThe timing score of a change outside every window0.750 to 1CompanyCompany admins, platform adminsrisk_config.out_of_window_score

Change windows count only while risk assessment is on.

Saving is refused for a change window whose times are out of range or equal (start_minute is 0 to 1439 and end_minute 0 to 1440 (minutes from midnight; 0 and 1440 are both midnight), and they cannot be the same), for a change freeze with another mode or without an end after its start (it needs a start and an end after the start), for two freezes with the same name (two change freezes have the same name "…": give each its own), for a freeze pattern that looks like a regular expression, and for a freeze that names a policy of another company.

General tab​

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Time zoneThe time zone of change windows, change freezes and the change calendarUTCAn IANA time zone name, such as Europe/IstanbulCompanyCompany admins, platform adminstimezone

What the merge request shows​

  • Policy card: the Risk and Change freeze lines of the decision checklist.
  • Risk assessment card: the score as a percentage and the level; Blocked or Allowed by … with the reason given and Allowed at …; the block reason; the four factor scores (Change window, Criticality, Footprint, MR size); added and deleted lines, N files changed, Footprint: with its category, the binary files, and Blackout: Yes or No. Allow risk for a held change.
  • My Work: Risk hold and Held by a change freeze as reasons.
  • The merge gate's check and the status comment on the merge request name the control holding the merge.

Audit log​

ActionWhenWho
mr_risk_blockedA new head commit's assessment holds the merge requestMerge Pilot
risk_allowSomeone accepted a merge request's risk (with the level, score, reason and release pool)person
mr_merged_in_freezeA merge request was merged during a change freeze that held itMerge Pilot
freeze_releaseSomeone let a held change go ahead during a freeze (with the freeze, commit, reason and release pool)person
update_companyThe company's settings, risk settings included, were savedperson
config_change_requestedA change to the risk settings waits for four-eyes reviewperson

See Audit log.

API fields​

WhereFieldMeaning
Policycontrols.risk.block_threshold"" (company), never, low, medium, high, critical
Policycontrols.risk.release_pool_idWho may accept the risk; null: the default
Policycontrols.freeze.exemptNo freeze holds the policy's changes or raises their risk
Policycontrols.freeze.release, controls.freeze.release_pool_idSomeone may release one held change during a freeze; who (null: the approvers, else company admins). POST /api/v1/merge-requests/{id}/freeze-release with reason and head_sha
Merge requestfreeze_releaseThe release: freeze, by, at, reason, head_sha
Merge requestdecision.freeze_releasableA freeze holds the change and its policy lets someone release it
PolicycriticalityThe service criticality: critical, high, medium, low, none or empty
Merge requestrisk_assessment.risk_level, risk_scoreThe level (low, medium, high, critical, unknown) and score
Merge requestrisk_assessment.change_window_score, criticality_score, footprint_score, mr_size_scoreThe factor scores
Merge requestrisk_assessment.out_of_window, in_blackoutOutside every change window; in a freeze
Merge requestrisk_assessment.added_lines, deleted_lines, changed_files, footprint_category, binary_filesWhat the size and footprint were computed from
Merge requestrisk_assessment.blocked, block_reasonHeld, and why
Merge requestrisk_assessment.allowed_by, allowed_at, allow_reasonWho accepted the risk, when and why
Merge requestrisk_assessment.head_sha, assessed_atThe commit assessed, and when
Merge requestmerged_in_freezeThe freeze a merge happened in
Merge requestwould_have_held_in_freezeWatched repositories: the freeze a merge happened in, which would have held it
Merge requestdecision.controls[] with control: "risk" or "freeze"Each control's status, blocking and reason

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Risk Assessment and Risk HoldsYouTube ↗