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.
| Role | What they can do |
|---|---|
| Every signed-in member of the company, auditors included | See the policies, open them read-only, see their history, use Which policy applies? and the Test run tab |
| Policy manager, company admin, platform admin | Also 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:
| Part | Shows |
|---|---|
| Name | The policy's name; select it to open the editor (read-only for other roles) |
| Description | The policy's description, below its name, when it has one |
| Catch-all badge | On the catch-all only |
| Change type badge | Normal, Standard or Emergency; a refusing policy shows Refuses instead |
| Inactive badge | The policy is switched off and is skipped (the row is dimmed) |
v<n> | The policy's current version |
| Conditions | One 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 chips | What 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) |
| Warnings | Problems with the order, see below |
Buttons on each row (policy managers and admins, except History):
| Button | What it does |
|---|---|
| Switch | Activates 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 |
| History | Opens the version history. Every member can use it |
| Edit | Opens the editor |
| Delete | Deletes 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:
| Warning | When |
|---|---|
| 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 means | Change approval | API |
|---|---|---|---|
| Normal change | Approvers 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 passes | Opened in the tracker before the merge; it must be approved | change_type: "normal" |
| Standard change | Pre-approved: no change approval is opened unless one is kept as a record. Merges once its checks pass | None, 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 change | Merges 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 it | change_type: "emergency" |
| Refuse | Nothing 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 path | None | deny: 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 does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| This policy sets its own rules | Uses the rules below instead of the company's | Off (the company's rules) | On or off | Policy manager, company admin, platform admin | emergency (object; left out: the company's rules) |
| Who may declare one | Only people of this approver pool may declare an emergency | Anyone who may label the change | Anyone who may label the change, or one of the company's approver pools | Same | emergency.pool_id |
| The author may not declare their own change an emergency | Someone other than the author must add the label | Off | On or off | Same | emergency.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 policy | No limit | Count 0 to 1000 (0: no limit); days 1 to 365, required with a count (the editor fills in 30) | Same | emergency.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 does | Default | Allowed values | Who can change it | API 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 log | None | Required; surrounding spaces are removed | Policy manager, company admin, platform admin | name |
| 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 instead | Empty | Any text | Same | description |
| Active (General) | Inactive policies are skipped; the next matching policy decides instead. Not shown for the catch-all, which is always active | On for a policy added in the editor; off when left out of an API request | On or off | Same (also the switch on the row) | active |
| Change type (Change type tab) | See Change types | Normal change | Normal change, Standard change, Emergency change, Refuse | Same | change_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 priority | Not set (change approvals then use normal) | With a priority map: Not set or one of the mapped priorities. Without one: free text | Same | priority |
| 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.1 | Not set | Not set, None, Low, Medium, High, Critical | Same | criticality ("", 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 opened | Open a new change approval | See below | Same | on_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 request | Block until fixed | See below | Same | on_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 does | API value |
|---|---|---|
| Open a new change approval | The old change approval is superseded and the new commits are approved from scratch | new_change_approval |
| Reopen the change approval | The 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 same | The 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 approval | keep_if_diff_unchanged |
| Keep the approval | The 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 does | API value |
|---|---|---|
| Block until fixed | The merge request stays open and cannot merge; it is checked again on every change | block |
| Close the merge request | Merge 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 request | close |
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.
| Template | How it is applied | Policies it sets (top to bottom) |
|---|---|---|
| Lightweight | Replaces | All 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 management | Replaces | Emergency 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) | Replaces | Emergency 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 bots | Adds | Dependency 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 branch | Required, main by default |
| Source branch | The source branch |
| Repository path | The repository's full path, such as team/payments |
| Author | The author's VCS username |
| The author is a bot | Whether the VCS reports the author as a bot |
| Draft | Whether the merge request is a draft |
| Labels | The labels |
| Changed files | One path per line. Leave empty when the diff is not known: policies on paths or size then cannot match |
| Changed lines | The 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_requeuejob 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
| Action | When |
|---|---|
policy_created, policy_updated, policy_deleted | A policy was created, saved or deleted. Details: name, version, change type, and open_mrs_requeued (how many open merge requests are evaluated again) |
policy_reordered | The order changed. Details: the new order and open_mrs_requeued |
policy_template_applied | A template was applied. Details: the template key and open_mrs_requeued |
config_change_requested | With four-eyes review on: a change was sent for review |
config_change_approved, config_change_rejected | A 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_matched | A 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 path | What it does |
|---|---|
GET /companies/{id}/policies?vcs_connection_id=… | The connection's policies in evaluation order, the catch-all last |
POST /companies/{id}/policies | Creates 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/reorder | Sets the order: vcs_connection_id and policy_ids, every policy above the catch-all exactly once |
GET /companies/{id}/policies/{policyId}/versions | The policy's versions |
GET /policy-templates | The templates |
POST /companies/{id}/policies/templates/{key} | Applies a template to vcs_connection_id |
POST /companies/{id}/policies/match | Which policy applies? |
POST /companies/{id}/policies/simulate | Test 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 |
Related pages
- Matching: conditions and patterns.
- Controls: what a policy checks, and the control modes.
- Approver pools: who approves.
- Core concepts: change approvals and the merge gate.
- Jobs: the background work a policy change starts.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →