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:
| Factor | Default weight | What it measures |
|---|---|---|
| Change window | 0.30 | When the change is assessed, against the company's change windows |
| Service criticality | 0.25 | The Service criticality of the policy that covers the change |
| Diff footprint | 0.25 | The riskiest kind of file the change touches |
| MR size | 0.20 | How many lines and files the change has |
Levels
The score gives the level:
| Level | Default: score at or above |
|---|---|
| Critical | 0.80 |
| High | 0.60 |
| Medium | 0.40 |
| Low | Below 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 policy | Default score |
|---|---|
| Critical | 1.0 |
| High | 0.75 |
| Medium | 0.5 |
| Low | 0.25 |
| None | 0.0 |
| Not set | 0.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:
| Category | Patterns | Score |
|---|---|---|
DB migration (db_migration) | **/migration*, **/schema.*, **/seed* | 1.0 |
CI/CD (ci_cd) | .gitlab-ci.yml, .github/**, Jenkinsfile | 0.9 |
Infra (infra) | **/deploy/**, **/helm/**, Dockerfile*, docker-compose*, values*.yaml, helmfile.yaml | 0.85 |
API (api) | **/api/**, **/handler*, **/service* | 0.5 |
Frontend (frontend) | **/frontend/**, *.tsx, *.jsx | 0.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 least | Score | Changed files, at least | Score | |
|---|---|---|---|---|
| 1,001 | 1.0 | 31 | 1.0 | |
| 501 | 0.75 | 16 | 0.75 | |
| 101 | 0.5 | 6 | 0.5 | |
| 51 | 0.25 | 3 | 0.25 | |
| 1 | 0.1 | 1 | 0.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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Risk | From which level the risk score holds the merge | Company setting (…): the company's hold, shown in brackets | Company 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 risk | Policy override of the company default | Policy managers, company admins, platform admins | controls.risk.block_threshold ("", never, low, medium, high, critical) |
| Who may lift a risk hold | Who 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 pools | Policy | Policy managers, company admins, platform admins | controls.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:
| State | Shown as | Merge gate |
|---|---|---|
| Risk assessment off | Not shown (skipped) | Not affected |
| The head commit not assessed yet | Assessing the latest commit's risk. | Not held |
| Below the hold level, or the policy never holds | Risk 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 risk | Risk 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 names | Who 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 owners | People who may approve the change under the policy (see Approval) |
| Neither | Company 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:
- On the risk score: while any freeze is in force, every change assessed scores critical (only while risk assessment is on).
- 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 value | Merge gate | Risk score |
|---|---|---|---|
| Hold merges | hold | Every merge is held: Change freeze … until …: merges are held. | Critical |
| Emergency changes only | emergency_only | Changes under an emergency policy pass (emergency changes may merge); every other change is held | Critical |
| Raise risk only | score | Not held by the freeze | Critical; 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 examplerelease/*) 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. (fieldwould_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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Enable risk assessment | Scores every merge request | Off | On, off | Company | Company admins, platform admins | risk_config.enabled |
| Block on risk | Holds merge requests at or above the block threshold until the risk is accepted, under policies that follow the company setting | Off | On, off | Company default (a policy can choose its own) | Company admins, platform admins | risk_config.block_on_risk |
| Block threshold | The lowest level held. Shown when Block on risk is on | High | Low, Medium, High, Critical (required when Block on risk is on) | Company default | Company admins, platform admins | risk_config.block_threshold |
| Change window weight, Service criticality weight, Diff footprint weight, MR size weight | Each factor's share of the score | 0.30, 0.25, 0.25, 0.20 | 0 to 1 each; together they must add up to 1 | Company | Company admins, platform admins | risk_config.weights.change_window, .service_criticality, .diff_footprint, .mr_size |
| Critical threshold, High threshold, Medium threshold | The score from which a change has that level | 0.80, 0.60, 0.40 | Rising: 0 < medium < high < critical ≤ 1 | Company | Company admins, platform admins | risk_config.level_thresholds.critical, .high, .medium |
| Criticality scores: Critical, High, Medium, Low, None | The score of each service criticality | 1.0, 0.75, 0.5, 0.25, 0.0 | 0 to 1 each | Company | Company admins, platform admins | risk_config.criticality_scores.critical, .high, .medium, .low, .none |
| Footprint rules (File pattern, Category, Score) | The company's own footprint rules; they replace the default rules | Empty: the default rules | File patterns; category DB migration, CI/CD, Infra, API, Frontend, Tests or Other; score 0 to 1 | Company | Company admins, platform admins | risk_config.footprint_rules[] (pattern, category, score) |
| Binary file footprint | The lowest footprint of a change adding or changing a binary file | 0.8 | 0 to 1; 0 does not score binaries | Company | Company admins, platform admins | risk_config.binary_score |
| Churn weight | The share of churn in the MR size score; file count gets the rest | 0.80 | 0 to 1 | Company | Company admins, platform admins | risk_config.size_churn_weight |
| Files not counted in the size | Files left out of churn and file count. Use the default list restores the defaults | The default list above | File patterns; empty counts every file | Company | Company admins, platform admins | risk_config.size_exclude (absent or null: the default list; []: none) |
| Churn thresholds (Min churn (lines), Score) | Scores for line churn; they replace the defaults | Empty: the defaults above | Minimum 0 or more; score 0 to 1 | Company | Company admins, platform admins | risk_config.size_thresholds[] (min_churn, score) |
| File count thresholds (Min files, Score) | Scores for the number of changed files; they replace the defaults | Empty: the defaults above | Minimum 0 or more; score 0 to 1 | Company | Company admins, platform admins | risk_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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Change freezes: Freeze name, Start, End, Freeze mode | A period during which merges are held, or the risk raised | None. A freeze added in the UI starts as Hold merges; one sent through the API without a mode is Raise risk only | A 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) | Company | Company admins, platform admins | risk_config.blackout_periods[] (name, start, end, mode: hold, emergency_only, score) |
| Freeze scope: Repositories (path patterns), Target branches, Only changes under these policies | Narrow a freeze to some repositories, branches or policies | Empty: every one | Glob patterns (a regular expression is refused); policies of the company (another is refused) | Company | Company admins, platform admins | risk_config.blackout_periods[].projects, .branches, .policies |
| Change windows: Window name, days, Start time, End time, Score | The times changes are expected, and the timing score inside each | None. A window added in the UI starts as 09:00 to 17:00 with score 0.25 | Days 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 1 | Company | Company admins, platform admins | risk_config.change_windows[] (name, day_of_week, start_minute, end_minute, score) |
| Out-of-window score | The timing score of a change outside every window | 0.75 | 0 to 1 | Company | Company admins, platform admins | risk_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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Time zone | The time zone of change windows, change freezes and the change calendar | UTC | An IANA time zone name, such as Europe/Istanbul | Company | Company admins, platform admins | timezone |
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
| Action | When | Who |
|---|---|---|
mr_risk_blocked | A new head commit's assessment holds the merge request | Merge Pilot |
risk_allow | Someone accepted a merge request's risk (with the level, score, reason and release pool) | person |
mr_merged_in_freeze | A merge request was merged during a change freeze that held it | Merge Pilot |
freeze_release | Someone let a held change go ahead during a freeze (with the freeze, commit, reason and release pool) | person |
update_company | The company's settings, risk settings included, were saved | person |
config_change_requested | A change to the risk settings waits for four-eyes review | person |
See Audit log.
API fields
| Where | Field | Meaning |
|---|---|---|
| Policy | controls.risk.block_threshold | "" (company), never, low, medium, high, critical |
| Policy | controls.risk.release_pool_id | Who may accept the risk; null: the default |
| Policy | controls.freeze.exempt | No freeze holds the policy's changes or raises their risk |
| Policy | controls.freeze.release, controls.freeze.release_pool_id | Someone 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 request | freeze_release | The release: freeze, by, at, reason, head_sha |
| Merge request | decision.freeze_releasable | A freeze holds the change and its policy lets someone release it |
| Policy | criticality | The service criticality: critical, high, medium, low, none or empty |
| Merge request | risk_assessment.risk_level, risk_score | The level (low, medium, high, critical, unknown) and score |
| Merge request | risk_assessment.change_window_score, criticality_score, footprint_score, mr_size_score | The factor scores |
| Merge request | risk_assessment.out_of_window, in_blackout | Outside every change window; in a freeze |
| Merge request | risk_assessment.added_lines, deleted_lines, changed_files, footprint_category, binary_files | What the size and footprint were computed from |
| Merge request | risk_assessment.blocked, block_reason | Held, and why |
| Merge request | risk_assessment.allowed_by, allowed_at, allow_reason | Who accepted the risk, when and why |
| Merge request | risk_assessment.head_sha, assessed_at | The commit assessed, and when |
| Merge request | merged_in_freeze | The freeze a merge happened in |
| Merge request | would_have_held_in_freeze | Watched repositories: the freeze a merge happened in, which would have held it |
| Merge request | decision.controls[] with control: "risk" or "freeze" | Each control's status, blocking and reason |
Related pages
- Controls: every control and how modes work.
- Approval: approvals that depend on the risk level.
- Approver pools: the pools a release pool is chosen from.
- Change policies: the policy's change type and service criticality.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →