Approval
The Approval control decides who signs off a change before it may merge. For a normal change, Merge Pilot opens a change approval in the tracker, assigns it to someone who may decide it, counts the votes cast in the tracker and in Merge Pilot, and opens the merge gate once the policy's approvals are met. The same control sets the separation of duties, the review of emergency changes and what happens to an approval when new commits arrive.
For a short overview of what it is for, see the Approvals & separation of duties feature page.
It is set in the policy editor on the Approval tab (who approves, separation of duties, assignment) and the Lifecycle tab (new commits, failures). Both tabs are unavailable for a policy that refuses its changes.
What the change type does
| Change type | Change approval | Effect on the merge gate |
|---|---|---|
| Normal change | Opened once the work items check out and no risk hold applies | The gate waits until the change approval is approved by enough people, and is blocked when it is rejected |
| Emergency change | Opened for a review afterwards | Never holds the merge: the change merges once its other controls pass, and approvers review it within the Review deadline |
| Standard change | None, unless Open a change approval as a record is on | Never holds the merge: pre-approved |
| Refuse | None | Every covered change is blocked by the policy itself |
Without a tracker linked to the VCS connection, a normal change cannot be approved: the control fails with No issue tracker is configured for this project, so the change cannot be approved. (see VCS connection settings).
States of the control (normal change)
| State | Shown as | Merge gate |
|---|---|---|
| Work items or a risk hold not cleared yet | A change approval is opened once the work items check out and no risk hold applies; CI and scans can still run. | Waits |
| Being opened | Creating the change approval. | Waits |
| Opening failed | The change approval could not be created (…); it is retried automatically. | Blocked |
| Too few people may approve | Only N people may approve this change, too few for any of the policy's approval groups (at least M approvals); add approvers, then resync. | Blocked |
| Waiting for votes | Waiting for KEY to be approved., or Waiting for KEY: 1 of 2 approvals. | Waits |
| Approved | KEY approved. | Passes |
| Rejected | KEY was rejected. | Blocked |
| Watched repository | Would need a change approval approved (N people may approve); the repository is watched, so no change approval is opened. | Not written to the VCS |
For an emergency change: Emergency change: may merge now; a change approval for the review afterwards is being created., then Emergency change: may merge now; KEY must be reviewed afterwards by …, and then Emergency change: reviewed and approved in KEY. or, when the review was rejected, Emergency change: its review in KEY was rejected. (shown as failed, but it never holds the merge). A review decided after the merge is shown on the merge request the same way. Without an issue tracker for the project no review change approval is opened (Emergency change: may merge now; no issue tracker is configured for this project, so no change approval is opened for the review afterwards.), nor in a watched repository (… the repository is watched, so no change approval is opened for the review afterwards.). For a standard change: Standard change: pre-approved., with recorded as KEY when a record is kept.
Who must approve
Who must approve (Approval tab) lists one or more ways to approve. The change approval is approved when any one way is met; a way is met when each of its requirements has its approvals. For example: 1 of Security and 2 of Operations, or 1 of the change advisory board.
- Or another way to approve adds a way (at most 5). Remove this way removes one.
- And approvals from adds a requirement to a way (at most 5 per way).
- Each requirement asks for a number of approvals (1 to 20) from one of:
- The project's approver roles: people holding one of the repository roles chosen as approver roles for the project (from the VCS connection's Approver roles, Developer, Maintainer and Owner on GitLab or Write, Maintain and Admin on GitHub unless set), less the connection's excluded users;
- an approver pool (see Approver pools);
- Code owners of the changed files (see Code owners).
- Manage approver pools opens the pools page.
A new policy asks for one approval from the project's approver roles; so does a policy that names no requirement.
How votes are counted:
- One vote fills one seat. Someone in two pools counts once, where it helps most.
- A vote cast in Merge Pilot and an approval in the tracker by the same person count once.
- Extra votes beyond what a requirement needs fill nothing.
Approvals by risk level
By risk level on a requirement sets a different number of approvals for each risk level: low, medium, high, critical and unknown (Approvals at risk level (empty: N):). A level left empty takes the requirement's number. Unknown risk (a change too large to read) needs the most any level needs, unless it is set. Without a risk assessment the requirement's number applies. See Risk.
When the merge request's risk level changes, or the policy is edited, the votes already cast are counted again under the new numbers. A change approval that reaches the new quorum is approved (change_approval_quorum_met_on_policy_change); one already decided keeps its status, and a raised quorum shows as not met and takes more votes.
Several approvals need the tracker's reopen status
A normal policy that can need more than one approval at some risk level can be saved only when the tracker connection has a reopen status: each partial approval made in the tracker moves the change approval back for the next approver. Without one the editor says Several approvals need the tracker's reopen status… and saving is refused.
Saving is also refused when an approver pool that lists its people has fewer members than the policy asks from it. When it has exactly as many, the editor warns that a change by one of them cannot get its approvals from the pool (the author's own vote never counts).
Code owners
A Code owners of the changed files requirement asks the owners of the changed files, as the CODEOWNERS file on the target branch names them, instead of a pool:
- One approval is needed from each set of owners (a GitLab section's own count applies). One approval counts for every set its voter belongs to.
- The file is read from
.github/CODEOWNERS,CODEOWNERSordocs/CODEOWNERSon GitHub, and fromCODEOWNERS,docs/CODEOWNERSor.gitlab/CODEOWNERSon GitLab; the first found is used. A file over 3 MB is not read. Optional GitLab sections need no approval. - Owners are people:
@login, or an e-mail of a Merge Pilot user who linked their VCS account. Teams, groups and role entries are not asked; the merge request lists them as Not asked from …. A file owned only by such entries needs an approval nobody can give. - Owners need write access to the repository (Developer or above on GitLab, Write or above on GitHub) and must not be excluded.
- A change touching no owned file needs one approval from the project's approver roles instead.
- Until the code owners are read for the head commit, or when they cannot be read, the requirement cannot be met.
- A code owners requirement asks for one approval per set: its number and By risk level cannot be changed.
Who may approve
For a vote to count, the person:
- is not the merge request's author, ever;
- has an active Merge Pilot account in the company and has linked their account on the merge request's VCS in My profile (tracker approvals under the lenient setting excepted, below);
- fills a requirement: holds one of its repository roles on the repository with their own linked account, is not on the connection's or project's exclude list, is listed in the pool (unless the pool takes everyone holding its roles), or is a code owner of the changed files;
- is allowed by the separation of duties (below);
- or stands in for an approver who delegated to them, for the requirements whose roles they hold themselves (see Stand-ins).
Votes
In Merge Pilot
The merge request's Approval card has Approve and Reject for people who may vote.
- Approve asks for confirmation (Your approval counts as one of the N needed.).
- Reject asks Why is it rejected?: a reason of at least 5 characters is required. By default one rejection rejects the change approval, and the author is told why; the policy can ask for more (see Rejections).
- A comment (through the API also on an approval) is at most 2,000 characters.
- A new vote replaces the person's earlier vote on the same change approval.
- Merge Pilot comments on the change approval in the tracker (… approved this change in Merge Pilot (1 of 2 approvals).) and, once it is decided, moves it to the tracker's approved or rejected status.
- A decision made in Merge Pilot is recorded as one made in the tracker:
mr_approvedorchange_approval_rejected, the Change approval approved or Change approval rejected notification, and a comment on the merge request saying who approved or rejected it. - Being the change approval's assignee is not needed: In Jira, only the change approval's assignee decides it applies to moves in the tracker only.
- Authors see You wrote this change, so you cannot vote on it. instead of the buttons. The author is recognised by the VCS account the person linked in My profile for the merge request's VCS connection, as when the vote itself is checked. Auditors cannot vote, and nobody votes on a standard change or on a watched repository.
API: POST /api/v1/merge-requests/{id}/votes with decision (approve or reject) and comment (required to reject, at least 5 characters once trimmed). It acts as a person: a session or a personal API token.
In the tracker
Moving the change approval to its approving status in the tracker is an approval by whoever moved it; moving it to its rejecting status is a rejection, also from the approving status (the approval is then withdrawn). Moving an approved change approval out of its approving status withdraws the approval only when someone who may decide it (under the company's tracker approvals setting below, never the author) or a company or platform admin does it, in Jira and in the built-in tracker; anyone else's move is undone and written as change_approval_vote_ineligible. In the built-in tracker the review check boxes a decision rests on are ticked only by who may decide it, never the author (see Who decides a change approval).
- When more approvals are still needed, Merge Pilot records the approval and moves the change approval back to the reopen status for the next approver (approval by … recorded (1 of 2). Another approver must approve this change approval.).
- An approval the tracker does not name anybody for never counts.
- The author's own approval is ignored: the change approval goes back, the merge request is told why, and
change_approval_self_approval_blockedis written. The author's own rejection is ignored the same way and written aschange_approval_vote_ineligible, in either mode below: the author never decides. - A decision by someone who may not decide is ignored: the change approval goes back for a decision (an approved one someone may not reject goes back to its approving status), the merge request gets a comment, and
change_approval_vote_ineligibleis written.
Two company settings decide whose tracker decisions count (company page, Approvals tab):
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Approvals made in the tracker | Only from people who linked their VCS account: an approval or rejection counts only when the tracker names who made it and that person is an active Merge Pilot user of the company who linked their account on the merge request's VCS; only someone who may approve may reject. From any Merge Pilot user: an approval counts when the tracker names a Merge Pilot user of the company, even without a linked VCS account (separation of duties then knows them by e-mail); rejections are not checked, except that the author's never counts | Only from people who linked their VCS account | strict, lenient | Company | Company admins, platform admins | tracker_approvals |
| In Jira, only the change approval's assignee decides it | Approvals and rejections in Jira by anyone but the assignee are ignored, and the change approval goes back for a decision. The built-in tracker always works this way. Votes in Merge Pilot are not limited to the assignee | Off | On, off | Company | Company admins, platform admins | tracker_assignee_only |
| Decide Jira change approvals in Jira only | Change approvals in Jira are decided in Jira only: no Approve, Reject or Withdraw in Merge Pilot (the API answers 409). The built-in tracker is not affected | Off | On, off | Company | Company admins, platform admins | tracker_decisions_only |
People in the tracker are matched to Merge Pilot accounts by their tracker account, their e-mail or their user name, as the company's People settings say. An identifier that matches more than one account counts for nobody.
With Only from people who linked their VCS account (the default), a decision in the tracker counts only from someone who may approve the change, as a vote in Merge Pilot does: they hold one of the approver roles on the repository (the repository's own, else the connection's; a pool's when it sets them). Anyone else's decision is ignored and the change approval goes back, whatever the tracker lets them do. So the count of people who may approve, the merge request page's Approve, Reject and Take over, and decisions in the tracker follow the same rule. When nobody may approve (no one with the roles has linked their account), the merge request is held with Nobody may approve this change … and no change approval is opened until someone can. With From any Merge Pilot user the person behind a tracker decision may not be known, so the roles are not checked there.
- An approval in the tracker of a change approval Merge Pilot has rejected is undone: the change approval goes back to its rejected status with the comment this change approval is rejected, and an approval does not undo a rejection. Whoever rejected it, or a company administrator, can withdraw the rejection on the merge request's page in Merge Pilot …
Rejections
A rejection is always recorded. The policy decides when rejections reject the change approval (Approval tab):
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| When rejections reject | One rejection rejects. Every approval group has a rejection from one of its approvers: a rejection holds the groups its voter can approve in; the change approval is rejected once no way to approve is left without one. More people reject than approve: rejected while the rejections outnumber the approvals | One rejection rejects | any, per_requirement, majority | Policy | Policy managers, company admins, platform admins | controls.approval.rejection_mode |
| Rejections can be withdrawn | Before the merge, whoever rejected (or stood in for the rejecter), or a company administrator, can withdraw a rejection with a reason. Off: a rejection is final | On | On, off | Policy | Policy managers, company admins, platform admins | controls.approval.no_withdraw (true: off) |
- A rejection that does not reject yet is commented on the change approval (rejection by … recorded (N so far). It does not reject the change yet: …); a tracker rejection moves it back to its reopen status so others can still decide it.
- Under More people reject than approve, a rejection made in the tracker of an approved change approval whose approvals still outnumber the rejections leaves it approved: the tracker is moved back to its approved status, with a comment.
- Withdraw is next to a rejection in the merge request's votes list. It asks Why is it withdrawn? (at least 5 characters). The change approval is decided again from the remaining votes (open, approved, or still rejected by others) and the tracker follows: back to its reopen status, or to its approved status. A withdrawn rejection stays withdrawn even when the tracker cannot be moved back (for example when the tracker connection has no reopen status). The audit log gets
change_approval_rejection_withdrawn. - API:
POST /api/v1/merge-requests/{id}/rejection/withdrawwithvoter(default: the caller) andreason.
Approval fatigue
When one person approves many change approvals in a short time, Merge Pilot warns (it never blocks). Approvals in the tracker and in Merge Pilot count alike, and each change counts once per person, even when they approve it again. Company page, Approvals tab, card Approval fatigue guard:
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Enable approval fatigue detection | Turns the warning on | Off | On, off | Company | Company admins, platform admins | approval_fatigue.enabled |
| Lookback days | The period counted | 7 | 1 to 90 | Company | Company admins, platform admins | approval_fatigue.lookback_days |
| Threshold | Approvals by one person in the period that trigger the warning | 5 | 1 to 1,000 | Company | Company admins, platform admins | approval_fatigue.threshold |
The warning is shown on the Approval card (Approval concentration: …, one line for each approver who raised one on the change; a warning stays once raised), written as approval_fatigue_detected and sent as the Approval fatigue notification.
Separation of duties
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| The author | The merge request's author never approves, rejects, takes the change approval or accepts its risk | Always | Not configurable | Not a setting | Nobody | None |
| People who committed to the change | Whether someone who authored or committed a commit of the change may approve it. People are matched by their linked VCS account and their e-mail. May approve: allowed. May approve, flagged: allowed and flagged on the merge request and in compliance. May not approve: their approvals, in Merge Pilot and in the tracker, are refused, and they are not assigned the change approval. The rule restricts approving only: they may still reject, since a rejection only stops the change | May not approve | off, flag, block | Policy | Policy managers, company admins, platform admins | controls.approval.separation.committers |
| An approver merging the change | Whether someone who approved the change may merge it. Merging cannot be stopped in the VCS. Allowed. Allowed, flagged: the merge is flagged (mr_sod_flag). Non-compliant: the merge is marked non-compliant, written as mr_sod_block and the administrators are alerted (notification Merged without approval, title Separation of duties broken). The policy list then shows the chip Approver merges flagged non-compliant | Allowed | off, flag, block | Policy | Policy managers, company admins, platform admins | controls.approval.separation.merger |
The committer rule applies to stand-ins too: someone standing in for an approver who committed to the change is treated as a committer.
The merge request shows the flags: Separation of duties: …, or Separation of duties broken: … for a non-compliant merge.
Change approval deadline
A normal change's change approval can have a deadline, after which it is overdue.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Change approval deadline | How long the change approval may stay open before it is overdue: empty for the company's setting, 0 for no deadline, at most 2160 hours. Shown for normal policies; the field shows the company's value while it is empty | Empty: the company's setting | Empty, or 0 to 2,160 hours (90 days) | Policy override of the company default | Policy managers, company admins, platform admins | controls.approval.due_hours (left out: the company's) |
| Change approval deadline (hours) (company, Approvals tab) | The company default for normal changes | 0: no deadline | 0 to 2,160 | Company default | Company admins, platform admins | change_approval_due_hours |
The deadline is set when the change approval is created: its creation time plus the hours in force then. A change approval opened again (reopened for new commits, or its approval revoked in the tracker) gets a new deadline: that moment plus the hours in force then. When a quarter of the time to the deadline is left, and at most a day before it, Change approval due soon (change_approval_due_soon) is sent (a day before a deadline of four days or more, 30 minutes before a two-hour one); once it passes and the change approval is still open, Change approval overdue (change_approval_overdue), both to the routes that take them and to the change approval's assignee (see Events → Change approval deadlines). Each is also written to the audit log. Saving due_hours on a policy that is not a normal change is refused (400). The merge request records the deadline as issue_tracker.change_approval_due_at.
Emergency changes
Review deadline
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Review deadline | How long after the change approval is opened approvers have to review an emergency change. Shown for emergency policies | 72 hours | 1 hour or more | Policy | Policy managers, company admins, platform admins | controls.approval.review_hours |
The review is a vote like any other, with the same Who must approve and the same checks, before and after the merge: the author never decides it, only the policy's approvers count, it takes the policy's number of approvals, and the company's tracker approval settings apply. After the merge it can be decided in the tracker or with Approve and Reject on the merge request's Approval card; the decision is recorded with who made it (change_approval_decided_after_mr_merged). When a quarter of the review time is left, and at most a day before the deadline, Change approval due soon is sent (18 hours before a 72-hour review deadline, 6 hours before a 24-hour one); a review reopened for new commits gets a new deadline; a review past its deadline is flagged on the dashboard, written as emergency_review_overdue and sent as Emergency review overdue.
Who may declare an emergency
A change becomes an emergency when an emergency policy covers it, usually because of a label such as emergency. Whoever added the label the policy matches on declares the emergency; for a policy that matches on something else, the author does. By default anyone who may label the change may declare one, so a hotfix never waits. Every declaration is recorded on the merge request, written as emergency_declared and sent as the Emergency declared notification.
The company limits who may declare an emergency (company page, Approvals tab, card Emergency changes). An emergency policy can set its own rules instead (Who may declare an emergency, switch This policy sets its own rules).
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| This policy sets its own rules | Replace the company's rules for this emergency policy | Off: the company's rules | On, off | Policy (emergency policies only) | Policy managers, company admins, platform admins | emergency (absent: the company's) |
| Who may declare one | Anyone who may label the change, or only people of one approver pool who hold its roles on the repository | Anyone who may label the change | Anyone, or one of the company's approver pools | Company default / policy override | Company: company admins, platform admins. Policy: policy managers, company admins, platform admins | emergency.pool_id |
| The author may not declare their own change an emergency | Someone else must add the label | Off | On, off | Company default / policy override | As above | emergency.not_author |
| Limit emergencies per repository (company), At most … per repository in … days (policy) | Once a repository has had this many emergencies in the window, further ones are not emergencies | No limit | 1 to 1,000 emergencies in 1 to 365 days. The company form starts at 3 in 30 days; the policy fills 30 days when a number is typed | Company default / policy override | As above | emergency.quota_count, emergency.quota_days |
When the rules are not met, or who added the label cannot be read from the VCS, the emergency policy does not match and the next matching policy covers the change. Both policy testers apply the emergency rules and show why (see Trying policies out). Emergency rules on a policy that is not an emergency policy are refused.
Standard changes
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Open a change approval as a record | Opens a change approval for standard changes too, to keep an audit trail in the tracker, without asking anyone to approve | Off | On, off | Policy (standard policies) | Policy managers, company admins, platform admins | controls.approval.record_standard |
New commits and failures
On the Lifecycle tab.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| New commits after a change approval | Open a new change approval: the old one is superseded and the new commits are approved from scratch. Reopen the change approval: the same change approval goes back for approval and its votes are cleared. Keep the approval while the change is the same: the approval stays when the lines the change adds and removes are the ones approved, as after a rebase or 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. Lines that look like diff headers inside the change (such as ++i; or -- comment) count as changed lines. Unchanged context lines are not compared, so moving identical lines elsewhere in the same file keeps the approval. Keep the approval: the change approval and its approval stay valid for later commits (change_approval_new_commits_kept) | Open a new change approval | new_change_approval, reopen_change_approval, keep_if_diff_unchanged, keep | Policy | Policy managers, company admins, platform admins | on_new_commits |
| Missing work items or a rejected change approval | Block until fixed: the merge request stays open and cannot merge; it is checked again on every change. Close the merge request: a rejected change approval (or missing work items) closes it, and the author has to open a new one | Block until fixed | block, close | Policy | Policy managers, company admins, platform admins | on_fail |
- Reopen the change approval needs the tracker's reopen status. When there is none, or reopening fails, a new change approval is opened instead.
- A rejected or cancelled change approval is replaced by a new one when new commits are pushed or the merge request is reopened, whatever the setting.
- A merge request moved to another target branch gets a new change approval: an approval into one branch is not one into another.
- When the policy covering a merge request no longer uses a change approval, its open change approval is retired.
- For a standard policy without a record there is nothing to supersede or reopen, and the editor says so.
Assignment
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Assign the change approval | Who the tracker shows as the assignee. Any eligible approver can still vote. A random approver. Approvers in turn: the one assigned least recently first. The least busy approver: the one with the fewest open change approvals. Nobody (whole pool): the change approval is opened unassigned | A random approver | random, round_robin, least_loaded, unassigned | Policy | Policy managers, company admins, platform admins | controls.approval.assignment |
| When nobody can be assigned | What happens when nobody holding the approver roles may take the change approval: it is opened unassigned and the merge request says so (No eligible approver: …). The company's setting (…). Wait for someone to take it. Assign it as soon as someone can: the periodic re-check gives it to the first person who may take it. Not shown for Nobody (whole pool) | The company's setting | "" (company), manual, auto | Policy override of the company default | Policy managers, company admins, platform admins | controls.approval.no_approver |
| When nobody can be assigned a change approval (company, Approvals tab) | The company default: Leave it for someone to take or Assign it as soon as someone can | Leave it for someone to take | manual, auto | Company default | Company admins, platform admins | no_approver |
The change approval is never assigned to the author, the VCS connection's own account, an excluded user, a committer the policy keeps out, or someone without a Merge Pilot account and a tracker account Merge Pilot can find.
Taking a change approval
On the merge request's Approval card, Assign to me takes an unassigned change approval and Take over takes one assigned to someone else. Only someone who may approve it may take it, and only while it is open. A take-over is noted on the change approval, written as change_approval_taken_over (else change_approval_assign_me) and announced. When the policy only flags committers, a committer who takes it is flagged. API: POST /api/v1/merge-requests/{id}/assign-me.
Stand-ins
An approver who is away can name a stand-in for a period. During it the stand-in is assigned and votes in the approver's place, for the requirements whose roles the stand-in holds on the repository themselves, never as the author. The vote shows by …, standing in. Who may name stand-ins is set on the company page, Approvals tab, Who names stand-ins (see Approvals): Approvers and administrators (default), Approvers only, Administrators only or Off (API delegation: both, self, admin, off). Approvers name their own in My profile.
What the merge request shows
- Policy card: the Change approval line of the decision checklist.
- Approval card: the change approval's status (Approved, Rejected, Review pending for an emergency, or 1 of 2 approvals); Approvals needed, with each way to approve (separated by or) and each requirement's have of required and name (The project's approver roles when it names no pool); the Votes, each marked in tracker or in Merge Pilot; the approval concentration warning; Approve and Reject; the Assignee with Assign to me or Take over.
- Banners for an emergency declaration and for separation-of-duties flags.
- My Work: Change approval rejected as a reason on the author's change, and Waiting for your approval on the open change approvals assigned to a person (their own changes excepted).
- On a watched repository: No change approval is opened while the repository is watched.
GitLab and GitHub
The control works the same on both. They differ in how the merge gate holds the merge (an approval rule approved by the bot user on GitLab, a required check on GitHub; see Core concepts), in the repository roles that can approve, and in where the CODEOWNERS file is read.
Audit log
| Action | When |
|---|---|
change_approval_created | A change approval was opened |
change_approval_vote | A vote was counted |
change_approval_vote_ineligible | A decision was ignored: the person may not decide this change |
change_approval_self_approval_blocked | The author's approval in the tracker was ignored |
mr_approved, change_approval_rejected | The change approval was approved or rejected |
change_approval_rejection_withdrawn | A rejection was withdrawn (with the voter, reason and the status after it) |
change_approval_superseded, change_approval_reopened, change_approval_new_commits_kept | What new commits did to the change approval |
change_approval_quorum_met_on_policy_change | The votes already cast met the quorum after a policy or risk change |
change_approval_assign_me, change_approval_taken_over, change_approval_assigned | The change approval was taken, taken over, or assigned once someone could take it |
mr_approvers_short | Too few people may approve |
approval_fatigue_detected | One approver approved many change approvals in a short time |
emergency_declared, emergency_review_overdue | An emergency was declared; its review is overdue |
change_approval_due_soon, change_approval_overdue | A change approval's deadline is near (a quarter of its time left, at most a day); a normal change's deadline passed |
mr_sod_flag, mr_sod_block | An approver merged the change |
The full list is in the Audit log.
API fields
| Where | Field | Meaning |
|---|---|---|
| Policy | change_type | normal, standard, emergency |
| Policy | controls.approval.groups[].requirements[] | id, pool_id (null: the project's approver roles), source (code_owners), count (1 to 20), count_by_risk (low, medium, high, critical, unknown: 1 to 20) |
| Policy | controls.approval.assignment, no_approver, record_standard, review_hours, due_hours, rejection_mode, no_withdraw | As above |
| Policy | controls.approval.separation.committers, separation.merger | off, flag, block |
| Policy | emergency | pool_id, not_author, quota_count, quota_days |
| Policy | on_new_commits, on_fail | As above |
| Company | tracker_approvals, tracker_assignee_only, tracker_decisions_only, no_approver, change_approval_due_hours, delegation, emergency, approval_fatigue | The company's approval settings |
| Merge request | approval.groups[] | Each way to approve: met, and its requirements[] with id, name, required, approvers |
| Merge request | approval.votes[] | voter, decision (approve, reject), source (tracker, merge_pilot), comment, cast_by (a stand-in), fills, change_approval_key, at |
| Merge request | approval.approved, approved_by, approved_at, fatigue | The outcome |
| Merge request | issue_tracker.change_approval_key, change_approval_status, change_approval_assignee, change_approval_due_at, change_approval_overdue_at, review_due_at, assignment_problem | The change approval |
| Merge request | emergency | policy, label, by, at, is_author, error |
| Merge request | sod_flags, sod_violation | Separation-of-duties flags |
| Merge request | decision.controls[] with control: "approval" | The control's status, blocking and reason |
Related pages
- Change policies and Controls.
- Approver pools: the groups of people a requirement can name.
- Risk: risk levels and who may accept a risk.
- VCS connection settings: the tracker link, approver roles and exclude list.
- Jira and Built-in tracker: where change approvals live.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →