Skip to main content
3 video tutorials

Change policies

A change policy says how Merge Pilot governs a merge request: which merge requests it covers, what kind of change they are (standard, normal or emergency), and which controls must pass before the merge gate opens. Policies let one company treat a documentation fix, a dependency bot's update, a production release and an emergency hotfix each in its own way.

For a short overview of what it is for, see the Change policies feature page.

How a policy is chosen​

  • Policies belong to a VCS connection. Each VCS connection of the company has its own ordered list.
  • For each merge request, Merge Pilot tries the connection's policies from top to bottom and the first active policy that matches decides. Inactive policies are skipped.
  • The catch-all policy is always at the bottom. It has no conditions and covers every merge request no policy above it matches. It is always active and cannot be deleted or moved.
  • The merge request records the policy and the version of it that decided it. Later evaluations of the merge request use that version until the merge request is processed again (a new commit, a policy change, see Open merge requests after a change).

How conditions are written and evaluated is on the Matching page; what the controls do is on the Controls page.

The catch-all of a new connection​

A VCS connection starts with one policy, the catch-all Not covered by a policy, which refuses every merge request ("Ask a Merge Pilot administrator to add a policy for this kind of change."). Until someone adds policies or changes the catch-all, nothing on the connection can merge. Applying a template that replaces the policy set also replaces the catch-all.

The catch-all can be edited like any policy (change type, controls, approval, lifecycle), except that it has no conditions and cannot be made inactive.

Where to find it​

Governance → Change policies in the sidebar, shown once a company is selected. When the company has more than one VCS connection, a VCS connection list at the top chooses whose policies are shown.

RoleWhat they can do
Every signed-in member of the company, auditors includedSee the policies, open them read-only, see their history, use Which policy applies? and the Test run tab
Policy manager, company admin, platform adminAlso add, edit, activate and deactivate, reorder and delete policies, and apply templates

Platform admins see the selected company's policies. With four-eyes review on, changes made by these roles wait for a second person (see Four-eyes review).

The page​

The page header explains the rule: Each merge request is governed by the first active policy that matches it, top to bottom; the catch-all at the bottom covers the rest. (GitHub connections say pull request.)

Policy managers and admins see two buttons:

  • Templates: opens Start from a template.
  • Add policy: opens the editor for a new policy. A new policy is added above the catch-all, below the other policies.

The list​

Policies are listed in evaluation order (Policies in evaluation order), numbered from 1; the catch-all comes last, marked ∗. Each row shows:

PartShows
NameThe policy's name; select it to open the editor (read-only for other roles)
DescriptionThe policy's description, below its name, when it has one
Catch-all badgeOn the catch-all only
Change type badgeNormal, Standard or Emergency; a refusing policy shows Refuses instead
Inactive badgeThe policy is switched off and is skipped (the row is dimmed)
v<n>The policy's current version
ConditionsOne line summing up what it covers, for example into main, release/* · not drafts; Every merge request when it has no conditions, Everything no policy above matches for the catch-all
Control chipsWhat it asks for, for example Work item required, CI must pass, No high+ vulnerabilities, Secret scan (report), 2 approvals, Review within 72h, Committers cannot approve, Approver merges flagged non-compliant; Refuses every match for a refusing policy
Approvers:The approver pools its approval groups name (normal and emergency policies)
WarningsProblems with the order, see below

Buttons on each row (policy managers and admins, except History):

ButtonWhat it does
SwitchActivates or deactivates the policy. Not shown on the catch-all
Arrows (Move … up, Move … down)Moves the policy one place. Not shown on the catch-all
HistoryOpens the version history. Every member can use it
EditOpens the editor
DeleteDeletes the policy after a confirmation: Merge requests it covered fall through to the next matching policy. Its versions stay in the history. Not shown on the catch-all

When the list has no policy above the catch-all, it says No policies yet: every merge request falls through to the catch-all below. (or, when the catch-all refuses, …the catch-all below refuses every merge request, so nothing can merge.), with a link to start from a template.

Order warnings​

Merge Pilot checks the active policies of the list and warns on a policy's row when:

WarningWhen
Has no conditions, so the policies below it are never reached: …An active policy above the catch-all has no condition at all
Never reached: … above it covers every change it would.An active policy above has the same conditions or fewer, so it always matches first
Matches on changed files or size: when the VCS cannot send the diff (very large changes), it does not match and a later policy decides.The policy has a file or size condition

API: GET /api/v1/companies/{id}/policies/warnings?vcs_connection_id=… returns policy_id, kind (covers_all, shadowed, needs_diff) and others (the policy names concerned).

Re-evaluation in progress​

After a policy change, a line such as 12 open merge requests wait to be evaluated under the changed policies (in the background, after live events). shows how many are still waiting. It refreshes every 5 seconds until none are left. API: GET /api/v1/companies/{id}/policies/reevaluation?vcs_connection_id=… returns waiting.

Change types​

The change type says how a covered merge request is approved. It is chosen on the editor's Change type tab, together with the fourth outcome, Refuse.

Option (label in the UI)What it meansChange approvalAPI
Normal changeApprovers sign off a change approval before it can merge. The merge gate stays closed until the change approval is approved by the people the policy's approval groups ask for, and every enforced control passesOpened in the tracker before the merge; it must be approvedchange_type: "normal"
Standard changePre-approved: no change approval is opened unless one is kept as a record. Merges once its checks passNone, unless Open a change approval as a record is on (then one is opened for the record; nobody has to approve it)change_type: "standard"
Emergency changeMerges once its checks pass, even in a change freeze that allows emergencies; approvers review it afterwards, within the review deadline (72 hours unless the policy sets another)Opened for a review after the merge; the merge does not wait for itchange_type: "emergency"
RefuseNothing it covers can merge; the merge gate is blocked with Merge requests matching policy "…" are not allowed. followed by the policy's description. Use it for work that needs another pathNonedeny: true (the change type is kept but not used)
  • Normal and emergency changes need a tracker linked to the VCS connection (see VCS connection settings); without one, a normal change cannot be approved.
  • Controls apply to every change type: a standard or emergency change still waits for its enforced controls.
  • On a refusing policy, the Checks, Approval and Lifecycle tabs are disabled.
  • Who signs off, separation of duties, the review deadline and assignment are described on the Approval page.

Who may declare an emergency​

An emergency policy is usually matched by a label, such as emergency. The person who declares the emergency is whoever added the label the policy matches on (the author, when the policy matches on something else). By default the company's emergency rules apply (the company's Approvals tab, Emergency changes). An emergency policy can set its own rules on its Approval tab:

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
This policy sets its own rulesUses the rules below instead of the company'sOff (the company's rules)On or offPolicy manager, company admin, platform adminemergency (object; left out: the company's rules)
Who may declare oneOnly people of this approver pool may declare an emergencyAnyone who may label the changeAnyone who may label the change, or one of the company's approver poolsSameemergency.pool_id
The author may not declare their own change an emergencySomeone other than the author must add the labelOffOn or offSameemergency.not_author
At most … per repository in … days (empty: no limit)Once a repository has had this many emergencies in the window, further ones do not match this policyNo limitCount 0 to 1000 (0: no limit); days 1 to 365, required with a count (the editor fills in 30)Sameemergency.quota_count, emergency.quota_days

When the rules are not met, the emergency policy does not match and the next policy below decides (usually a normal change). When the VCS cannot say who added the label, a policy with limiting rules does not match either. Emergency rules can only be set on an emergency policy.

Policy fields​

The editor is a side sheet with the tabs General, Scope, Change type, Checks, Approval, Lifecycle and Test run. Its header sums up what the policy Covers and Requires. A new policy is saved with Create policy; an existing one with Save as new version. Closing the editor with unsaved edits asks Discard your changes?.

The fields of the policy itself (the tabs Scope, Checks and Approval have their own pages: Matching, Controls, Approval):

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
Name (General)The policy's name, shown in the list, on merge requests, in the merge gate, in status comments and in the audit logNoneRequired; surrounding spaces are removedPolicy manager, company admin, platform adminname
Description (General)Free text about the policy, shown on its row in the list. On a refusing policy it is added to the reason shown on the refused merge request, so it can tell the author what to do insteadEmptyAny textSamedescription
Active (General)Inactive policies are skipped; the next matching policy decides instead. Not shown for the catch-all, which is always activeOn for a policy added in the editor; off when left out of an API requestOn or offSame (also the switch on the row)active
Change type (Change type tab)See Change typesNormal changeNormal change, Standard change, Emergency change, RefuseSamechange_type (normal, standard, emergency), deny
Priority (Change type)Shown in change approval titles and templates. When the linked tracker connection maps priorities, the list offers its mapped priorities and the mapped value is sent to Jira as the issue's priorityNot set (change approvals then use normal)With a priority map: Not set or one of the mapped priorities. Without one: free textSamepriority
Service criticality (Change type)Feeds the service-criticality factor of the risk assessment: a higher criticality raises the risk score of covered changes. None to Critical take the scores set on the company's Risk tab; Not set scores 0.1Not setNot set, None, Low, Medium, High, CriticalSamecriticality ("", none, low, medium, high, critical)
New commits after a change approval (Lifecycle)What happens to an existing change approval when commits are pushed after it was openedOpen a new change approvalSee belowSameon_new_commits
Missing work items or a rejected change approval (Lifecycle)What a failed work item check or a rejected change approval does to the merge requestBlock until fixedSee belowSameon_fail

Read-only fields returned by the API: id, company_id, vcs_connection_id, order (the place in the list), default (true for the catch-all), version, updated_by, created_at, updated_at.

New commits after a change approval​

Option (label in the UI)What it doesAPI value
Open a new change approvalThe old change approval is superseded and the new commits are approved from scratchnew_change_approval
Reopen the change approvalThe same change approval goes back for approval (moved to the tracker's reopen status)reopen_change_approval
Keep the approval while the change is the sameThe approval stays when the lines the change adds and removes are the ones approved (a rebase, a merge of the target branch). Any edit to them, or a change that cannot be compared (binary files, a diff the VCS does not send), opens a new change approvalkeep_if_diff_unchanged
Keep the approvalThe change approval and its approval stay valid for later commits. Each time this happens it is recorded in the audit log (change_approval_new_commits_kept)keep

A standard change without Open a change approval as a record has no change approval, so the editor shows that there is nothing to supersede or reopen.

Missing work items or a rejected change approval​

Option (label in the UI)What it doesAPI value
Block until fixedThe merge request stays open and cannot merge; it is checked again on every changeblock
Close the merge requestMerge Pilot closes the merge request; the author has to open a new one. Only a definite failure closes: a required work item that is missing or invalid while a tracker is configured, or a change approval that was rejected. A configuration problem never closes a merge requestclose

Versions and history​

  • Every save makes a new version (v1, v2, …). Creating a policy makes version 1, each edit adds one, and deleting a policy records a last version marked deleted. Versions are kept after a policy is deleted, so decisions already made keep referring to them.
  • Saving checks that nobody saved the policy in the meantime. If someone did, the save is refused: the policy was changed by someone else; reload and try again.
  • Each merge request records the policy version it was decided with.

History on a policy's row opens History of … (Each merge request records the version it was decided with.): every version, newest first, with what the save did (created, updated or deleted), who saved it (system for the catch-all Merge Pilot creates) and when, and what changed from the version before, named as the policy editor names it: the tab (and section), the field's label and its old and new values as the editor shows them, for example Approval → Open a change approval as a record: off → on, Checks → CI → Mode: Report → Enforce, Approval → Change approval deadline: no deadline → 48 hours, Change type: Normal → Refuse, or Approval → Who must approve → Group 1, requirement 1: approvals: 1 → 2.

API: GET /api/v1/companies/{id}/policies/{policyId}/versions returns the latest 200 versions, newest first, each with version, change, snapshot (the whole policy as saved), changed_by and changed_at.

Templates​

Templates opens Start from a template (Templates are a starting point; every policy stays editable.). Each template lists its policies with their change type, conditions and control chips.

  • Use this set (templates that replace) deletes the connection's policies and overwrites the catch-all with the template's. When the connection has policies, or the catch-all was edited, a confirmation asks first (Replace the policies with …?). The replaced policies' versions stay in the history.
  • Add to my policies (additive templates) puts the template's policies at the top of the list and keeps everything else.

Every template policy also reports Licenses, Package health and Dependency sources (the default for those three controls); other controls not listed below are off.

TemplateHow it is appliedPolicies it sets (top to bottom)
LightweightReplacesAll changes (the catch-all): normal change; work items reported, not required; CI enforced; secret scan reported; one approval from the project's approver roles
ITIL change managementReplacesEmergency changes: active; covers merge requests labelled emergency by human authors; emergency change reviewed within 72 hours; CI and secret scan enforced. Documentation: active; covers changes where only **.md or docs/** files changed; standard change; secret scan enforced. Normal changes (the catch-all): normal change; work item required; CI and secret scan enforced; dependency scan reported; one approval from the project's approver roles
Regulated (BDDK / SOX)ReplacesEmergency changes: active; covers merge requests labelled emergency by human authors; emergency change reviewed within 24 hours; work item required; CI and secret scan enforced; dependency scan reported. Normal changes (the catch-all): normal change; work item required, each work item covering at most 5 merged merge requests; one approving code review on the latest commit, and requested changes hold the merge; CI and secret scan enforced; dependency scan enforced from high severity; two approvals from the project's approver roles; committers may not approve; an approver merging the change is non-compliant
Dependency update botsAddsDependency updates: active; covers merge requests by the bots dependabot[bot] and renovate[bot]; standard change; CI and secret scan enforced; dependency scan enforced from high severity

In every template, committers may not approve their own change (the default), and the ITIL and Regulated emergency policies have a description telling authors to label the merge request "emergency".

API: GET /api/v1/policy-templates lists the templates (key, name, description, additive, policies); POST /api/v1/companies/{id}/policies/templates/{key} with {"vcs_connection_id": "…"} applies one. The keys are lightweight, itil, regulated and dependency_bots.

Trying policies out​

Which policy applies?​

Below the list, Which policy applies? takes a described change through the connection's saved policies, in order, as for a real merge request (Describe a merge request to see which saved policy decides it, and why the ones above it do not.). Nothing is changed.

Field (label in the UI)What to enter
Target branchRequired, main by default
Source branchThe source branch
Repository pathThe repository's full path, such as team/payments
AuthorThe author's VCS username
The author is a botWhether the VCS reports the author as a bot
DraftWhether the merge request is a draft
LabelsThe labels
Changed filesOne path per line. Leave empty when the diff is not known: policies on paths or size then cannot match
Changed linesThe number of changed lines

The company's emergency rules (or the policy's own) apply as for a real merge request. A described change has no one who declared the emergency, so an emergency policy whose rules limit who may declare one (an approver pool, not the author, or a per-repository limit) does not match and shows Who declared the emergency is not known; the policy's emergency rules need it.

Find the policy lists every policy in order with its result: Applies: this policy decides the change., Applies: no policy above matched, so the catch-all decides., Not reached: a policy above applies., Skipped: inactive., or the first condition the change does not meet, such as Target branch develop is not in main, release/*. The full list of reasons is on the Matching page.

API: POST /api/v1/companies/{id}/policies/match with vcs_connection_id, target_branch, source_branch, repo, author, author_bot, labels, draft, files and changed_lines. Each step of the answer has policy_id, name, default, active, applies, reached, change_type, deny and, when an active policy did not match, miss (condition, value, patterns, limit).

Test run​

The editor's Test run tab shows what the policies, with your unsaved edits, decide for a real merge request. Nothing is changed. Choose one of the connection's recently updated merge requests and select Run. The result shows Matched and the policy's name, its change type, the merge gate it would set (Can merge, Waiting or Blocked), Would open a change approval and Would close it when they apply, and the control checklist. A new policy needs a name before it can be tried.

The test run reads the merge request's current changes from the VCS and uses what Merge Pilot recorded about it (scans, CI, reviews, risk, work items, votes). Emergency rules apply as on the real merge request: who declared the emergency is read from the VCS, so an emergency policy matches only when its rules allow that person.

API: POST /api/v1/companies/{id}/policies/simulate with merge_request_id and, optionally, policies (a whole draft policy set to try instead of the saved one). The answer has policy, gate, controls, needs_change_approval, close, summary and facts (what the decision was made from).

Four-eyes review​

When the company turned on Review control changes (Company → Governance), adding, editing, activating or deactivating, deleting and reordering policies, and applying templates, do not take effect at once. The page shows Sent for review: another administrator or policy manager must approve the change, and the change waits in a box at the top of the page (1 change waits for a second person), with its summary (such as Update policy Normal changes (version 4)), who requested it and when.

  • Another policy manager, company admin or platform admin selects Approve (the change is applied) or Reject.
  • Nobody decides their own change (Another administrator must decide your change), and someone whose account the requester created, gave its role or set the password of cannot decide it either. A change requested with a service API token counts as its maker's.
  • People who may not decide see Waits for an administrator.
  • The change is checked (name, patterns, pools) when it is requested. When a policy create or edit is approved, the approver pools it names and the tracker's reopen status are checked again (they may have changed meanwhile): if a check fails, the approval is refused with the reason (the change could not be applied: …, HTTP 422) and the change is marked failed. An edit approved after someone else saved the same policy fails too, because the version no longer matches.
  • Approver pool changes are reviewed in the same way (see Approver pools).

API: a reviewed request answers 202 Accepted with {"pending": true, "change": {…}}. The waiting changes are at GET /api/v1/companies/{id}/config-changes, decided with POST /api/v1/companies/{id}/config-changes/{changeId}/approve or …/reject.

Open merge requests after a change​

Creating, editing, deleting or reordering a policy, or applying a template, has every open merge request of that VCS connection evaluated again under the new policy set, in the background:

  • change-managed merge requests first, then watched ones;
  • below live events, so new commits and votes are not held up (see the mr_requeue job on the Jobs page);
  • each merge request is matched again: it may move to another policy, gets the policy's new version, starts the scans the policy now runs, and has its merge gate and status comment updated.

When a merge request moves to a policy that does not use a change approval, its open change approval is retired. When the number of approvals asked changes, the votes already given are counted again under the new rules; if they are already enough, that is recorded (change_approval_quorum_met_on_policy_change). Merged and closed merge requests keep the decision and policy version they had.

Saving checks​

Besides the field rules, saving a policy is refused when:

  • a pattern looks like a regular expression (see Matching);
  • an approval group, the risk hold release, the freeze release or the emergency rules name an approver pool that is not the company's;
  • a normal change needs more approvals from a pool than the pool has listed members (pools that take everyone holding their roles are not counted this way). When the pool has exactly as many members as approvals needed, the policy is saved with a warning: when one of them authors a change, the pool cannot give enough approvals;
  • a normal change needs several approvals but the linked tracker connection has no reopen status (Several approvals need the tracker's reopen status…): each partial approval moves the change approval back, which needs that status.

Audit log​

ActionWhen
policy_created, policy_updated, policy_deletedA policy was created, saved or deleted. Details: name, version, change type, and open_mrs_requeued (how many open merge requests are evaluated again)
policy_reorderedThe order changed. Details: the new order and open_mrs_requeued
policy_template_appliedA template was applied. Details: the template key and open_mrs_requeued
config_change_requestedWith four-eyes review on: a change was sent for review
config_change_approved, config_change_rejectedA waiting change was decided. When an approved change is applied, the policy action above is also written, by the approver, with requested_by and approved_by
mr_policy_matchedA merge request was matched to a policy, or to a new version of it (written by Merge Pilot)

See Audit log.

API​

All paths are under /api/v1. Reading needs a signed-in member of the company; writing needs a policy manager, company admin or platform admin.

Method and pathWhat it does
GET /companies/{id}/policies?vcs_connection_id=…The connection's policies in evaluation order, the catch-all last
POST /companies/{id}/policiesCreates a policy (body: a policy with vcs_connection_id). Answers 201 with meta.warnings
PUT /companies/{id}/policies/{policyId}Saves a policy. The body must carry the version it was read at. Answers with meta.warnings
DELETE /companies/{id}/policies/{policyId}Deletes a policy (not the catch-all)
PUT /companies/{id}/policies/reorderSets the order: vcs_connection_id and policy_ids, every policy above the catch-all exactly once
GET /companies/{id}/policies/{policyId}/versionsThe policy's versions
GET /policy-templatesThe templates
POST /companies/{id}/policies/templates/{key}Applies a template to vcs_connection_id
POST /companies/{id}/policies/matchWhich policy applies?
POST /companies/{id}/policies/simulateTest run
GET /companies/{id}/policies/warnings?vcs_connection_id=…Order warnings
GET /companies/{id}/policies/reevaluation?vcs_connection_id=…Open merge requests still waiting for re-evaluation

Video tutorials

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

Your First Change Policies from a TemplateYouTube ↗
Scope a Policy by Branch, Files and LabelsYouTube ↗
Policy Order, Versions and HistoryYouTube ↗