Skip to main content
2 video tutorials

Approving and rejecting

A normal change needs its change approval approved before it may merge, and an emergency change needs it reviewed afterwards. Approvers decide it in one of two places: on the merge request page in Merge Pilot, or by moving the change approval in the tracker. Both count the same way, and one person counts once. This page describes the approver's side; what the policy asks for is set in the Approval control.

Where to vote​

Open the merge request in Merge Pilot (Merge requests → the merge request). The Approval card shows where the change approval stands and has the vote buttons; the Issue tracker card next to it shows the change approval itself, its assignee and Assign to me / Take over.

The other place is the tracker: moving the change approval to its approving status approves it, moving it to its rejecting status rejects it (see Decisions made in the tracker).

A company can have its Jira change approvals decided in Jira only (Company → Approvals → Decide Jira change approvals in Jira only, off by default). The Approval card then offers no vote buttons and says Change approvals are decided in Jira only at this company: approve or reject KEY there.; the API refuses votes and withdrawals with 409. The built-in tracker is not affected.

Who may vote​

A vote in Merge Pilot is accepted only from someone who:

  • is not an auditor (auditors read the page; they never see the buttons);
  • acts as a person: signed in, or with a personal API token (a service token is refused);
  • has linked their account on the merge request's VCS in My profile. Without it Merge Pilot cannot tell whether they wrote the change, so the vote is refused (link your account on this merge request's VCS in My profile before voting);
  • is not the author of the merge request, recognised by that linked account. Authors see You wrote this change, so you cannot vote on it. instead of the buttons;
  • fills one of the policy's requirements: holds one of its repository roles on the repository with their own linked account and is not on an exclude list, is in the named approver pool, or is a code owner of the changed files. Otherwise the vote is refused with the reason (you are not an approver for this change: you …, for example do not hold an approver role on the repository or are not in the approver pool "CAB");
  • or stands in for an approver who is away (see Stand-ins).

The page offers Approve, Reject and Take over only to someone these rules let decide; anyone else sees why not (for example You cannot vote: you are not an approver for this change: you do not hold an approver role on the repository.). Someone who committed to the change, under a policy that does not let committers approve, is offered Reject only, with You cannot approve: you committed to this change, and its policy does not let committers approve it. You can still reject it., and no Take over. A vote refused when it is judged says why in its dialog. The same rules apply to decisions made in the tracker (see Decisions made in the tracker).

Being the change approval's assignee is not needed to vote in Merge Pilot. The company's In Jira, only the change approval's assignee decides it governs moves made in the tracker only (see Decisions made in the tracker).

Separation of duties adds to this:

WhoApproveRejectTake the change approval
The merge request's authorNeverNeverNever
Someone who authored or committed a commit of the change, when the policy's People who committed to the change is May not approveRefused (you committed to this change, and its policy does not let committers approve it)AllowedRefused
The same, with May approve, flaggedAllowed, and the merge request is flagged (Separation of duties: …)AllowedAllowed, and flagged
Someone who approved and then merges the changeJudged at the merge, by An approver merging the change

Separation of duties restricts approving only: a committer kept out of approving may still reject, since a rejection only stops the change. See Separation of duties for the settings.

The buttons are shown only while a vote can count: the merge request is open (or merged, while its review is still undecided: an emergency change's review, or a late decision on a change merged without approval), its repository is under change management (not watched), the policy is not a standard change, and the change approval is open (or approved, while a raised quorum still needs more approvals). Nobody votes on a standard change (Standard change: pre-approved by its policy, no change approval needed.) or on a watched repository (No change approval is opened while the repository is watched.). Before the change approval exists the card says No change approval yet.

Approve and Reject​

Button (label in the UI)What happens
ApproveA confirmation, Approve <KEY>?: Your approval counts as one of the N needed. It is recorded in the audit log and on the change approval. (or, when one approval is enough, Your approval is recorded in the audit log and on the change approval.). Approve change records it (Approval recorded). The button then reads You approved and is disabled; a stand-in sees it for the vote they cast in an approver's place
RejectReject <KEY>?: Rejecting stops the change; the author is told why. Your vote and reason are recorded in the audit log and on the change approval. Why is it rejected? must be at least 5 characters. Reject change records it (Change rejected). Whether it rejects the change approval is the policy's When rejections reject (by default one rejection does; see Rejections)

After a vote:

  • Merge Pilot comments on the change approval in the tracker, for example Merge Pilot: alice approved this change in Merge Pilot (1 of 2 approvals)., with the comment when there is one.
  • When the votes meet the policy (or the rejections reject it), the decision is recorded exactly as one made in the tracker: mr_approved or change_approval_rejected in the audit log, the Change approval approved or Change approval rejected notification, and a comment on the merge request (change approval … approved by … or change approval … was rejected by …).
  • The change approval is then moved to the tracker's approved or rejected status. If the tracker cannot be reached, the vote still stands: the page shows The change approval is out of step with this page. … and Merge Pilot moves it later (see Scenarios).
  • The merge request is evaluated again, and the merge gate follows (see Merge gate). A merged change's review shows the decision and who made it, and writes change_approval_decided_after_mr_merged.

A vote is for the change approval and the commit it covers. If new commits or a retarget replace the change approval while you vote, the vote is refused (the change approval changed while you voted; reload and try again).

How votes are counted​

The Approval card shows the progress of the way to approve that is furthest along:

  • N of M approvals (amber) while waiting, Approved (green) once a way is met, Rejected (red) after a rejection. An emergency change shows Review pending until it is reviewed.
  • Approvals needed, when the policy has more than one way to approve or more than one requirement: each way, separated by or, and each requirement as have of required and its name (The project's approver roles when it names no pool), with who filled it.
  • Votes: each vote with who cast it, by …, standing in for a stand-in, in tracker or in Merge Pilot, when, and the comment.

The rules:

  • One vote fills one seat. Someone who belongs to two requirements counts once, where it helps most. One approval counts for every code owner set its voter owns.
  • A person's approval in the tracker and their vote in Merge Pilot count once.
  • Votes beyond what a requirement needs fill nothing.
  • When the merge request's risk level or the policy changes, the votes already cast are counted again under the new numbers (see Approvals by risk level). A change approval already approved stays approved, but when the policy now asks for more, the card shows the missing approvals and the buttons stay available until they are given.

Changing or withdrawing a vote​

  • A new vote replaces your earlier one on the same change approval. While the change approval is open you can turn an approval into a rejection.
  • There is no button to withdraw an approval, and once the change approval is approved or rejected, Merge Pilot takes no more votes on it (the change approval is already approved, the change approval is already rejected).
  • Withdrawing a rejection: while the merge request is open, Withdraw next to a rejection in the votes list is shown to whoever rejected and to company and platform admins. It asks Why is it withdrawn? (at least 5 characters); the change approval is decided again from the remaining votes and the tracker follows. A policy can turn this off (Rejections can be withdrawn). See Rejections.
  • Withdrawing an approval is done in the tracker: moving an approved change approval out of its approving status (to any status but a rejecting one) withdraws the approval. The move counts only when made by someone who may decide the change approval (an approver of the change under Approvals made in the tracker, below, never its author) or a company or platform admin, in Jira and in the built-in tracker alike; anyone else's move is undone: the change approval goes back to its approving status with a comment, change_approval_vote_ineligible is written, and the approval stands. Every vote on it goes, those cast in Merge Pilot included: the change needs a fresh quorum. The merge request gets a comment (change approval … was moved out of its approved status, so the approval was withdrawn. The change waits for approval again.) and waits for approval again. Merge Pilot's own moves (to the merged status, or back for new commits) are not withdrawals. See The approval is withdrawn.
  • New commits clear the votes as the policy's New commits after a change approval says: a new change approval, the same one reopened with its votes cleared, or the approval kept (see New commits are pushed).

Taking a change approval​

The change approval is assigned to one person in the tracker (see Assignment). Anyone who may decide it can still vote in Merge Pilot, whoever is assigned. To be the one the tracker shows, use the Issue tracker card:

Button (label in the UI)Shown whenWhat it does
Assign to meThe change approval is open and unassignedAssigns it to you in the tracker
Take overIt is open and assigned to someone elseReassigns it to you

Neither is shown to auditors, on a watched repository, or when you are already the assignee. Only someone who may decide the change approval may take it: not the author, someone with a linked VCS account who fills a requirement (or stands in for an approver who does), and not a committer the policy keeps out. Merge Pilot also needs your tracker account; without one: your tracker account is not known: ask an administrator to set it on the Users page.

The change approval gets a comment, Merge Pilot: Alice took this change approval. or … took this change approval over from bob. (with , standing in for … for a stand-in). A take-over (not a first assignment) sends the Change approval reassigned notification to the company's notification routes that receive it. A committer who takes it under May approve, flagged is flagged. Where only the assignee may decide in the tracker (the built-in tracker always; Jira with In Jira, only the change approval's assignee decides it), the previous assignee's decision in the tracker no longer counts.

Reassigned in Jira, the change approval follows: Merge Pilot records the new assignee (as it would name them itself, when it knows the person), My work shows it to the new assignee and no longer to the previous one, and the audit log records it (change_approval_reassigned_in_tracker). Unassigned in Jira, it stays unassigned: Merge Pilot does not give it to someone else on its own. In the built-in tracker, change approvals cannot be reassigned by hand; Assign to me and Take over are the way.

A change approval that nobody could be assigned shows No eligible approver: … under Assignee and waits for someone to take it, or is given to the first person who may take it, as the company or policy says.

API: POST /api/v1/merge-requests/{id}/assign-me (a person only: session or personal API token). It answers 409 when the change approval is no longer open, 403 with the reason when you may not take it.

Stand-ins​

An approver who is away can be given a stand-in for a period (see Stand-ins for approvers for who names them and how). While it runs:

  • the stand-in is assigned change approvals in the approver's place, and may take them;
  • when the stand-in cannot approve the change in their own right, their vote takes the approver's seat. The vote is shown under the approver's name with by <stand-in>, standing in, and the audit entry names both;
  • the stand-in must hold the seat's repository role themselves: a stand-in without it is refused, like anyone else;
  • nobody stands in for the change's author, and a stand-in for someone who committed to the change is treated as a committer;
  • when the company sets Who names stand-ins to Off, stand-ins stop counting.

Decisions made in the tracker​

Moving the change approval in the tracker is a vote by whoever moved it, judged as a vote in Merge Pilot is: with the company's default Approvals made in the tracker, it counts only from someone who holds one of the approver roles on the repository (or is in the approver pool, or a code owner, as the policy asks); anyone else's move is ignored and the change approval goes back:

  • to an approving status: an approval. When more approvals are still needed, Merge Pilot records it and moves the change approval back to the tracker's reopen status for the next approver (Merge Pilot: approval by … recorded (1 of 2). Another approver must approve this change approval.), and comments on the merge request;
  • to a rejecting status: a rejection, also from the approving status when the tracker's workflow allows that move. The merge request gets change approval … was rejected by …; an approval it had is withdrawn. Under the policy's More people reject than approve, a rejection of an approved change approval that its approvals still outnumber leaves it approved: Merge Pilot moves it back to the approved status with a comment (see Rejections).

A vote made in the tracker by someone Merge Pilot knows is recorded under their Merge Pilot user name, so their tracker and Merge Pilot votes show (and count for approval fatigue) as one person; someone it does not know keeps the name the tracker gave. A decision that decides the change approval is recorded as one made in Merge Pilot is: the audit entry, the notification and the merge request comment. The same rules apply to the review of a merged change (an emergency change, or a late decision on a change merged without approval): it is not taken as decided by whoever moves it first, but counts the policy's approvals from the policy's approvers, never from the author.

A decision that does not count is undone: the change approval is moved back for a decision (an approved change approval someone may not reject goes back to its approving status, the approval standing), the merge request gets a comment, and change_approval_vote_ineligible (or, for the author's own approval, change_approval_self_approval_blocked) is written. That happens when:

  • the author approved or rejected their own change: the author never decides their change's change approval, in the tracker or in Merge Pilot;
  • the tracker did not say who made the move;
  • the person may not decide this change (the reasons are those of Who may vote);
  • only the assignee may decide, and someone else moved it. This setting, In Jira, only the change approval's assignee decides it, applies to moves in the tracker only, never to votes in Merge Pilot.

Whose tracker decisions count is a company setting, Approvals made in the tracker (company page, Approvals tab; see Tracker approvals):

Option (label in the UI)ApprovalsRejections
Only from people who linked their VCS account (default, strict)Count only from an active Merge Pilot user of the company, named by the tracker, who linked their account on the merge request's VCS and may approveCount only from someone who may approve
From any Merge Pilot user (lenient)Count from a Merge Pilot user of the company named by the tracker, even without a linked VCS account (separation of duties then knows them by e-mail)Not checked, except that the author's rejection never counts

When the policy names no approver pool and no code owners, a tracker decision is not checked against the repository roles: the tracker's own permissions decide who can move the change approval. People in the tracker are matched to Merge Pilot accounts as the company's People settings say. More in Approval → In the tracker.

Approval fatigue​

When the company turns on the Approval fatigue guard (see Approval fatigue guard), each approval is checked: if the approver has approved as many change approvals as the threshold within the lookback days (this one included, and counted once even when they approve it again; in the tracker and in Merge Pilot alike), Merge Pilot warns. It never blocks: the approval counts.

  • The Approval card shows Approval concentration: <approver> approved N change approvals in D days (threshold: T), one line for each approver who raised a warning on the change. A warning stays once raised: later votes by others do not clear it.
  • approval_fatigue_detected is written and the Approval fatigue notification is sent.
  • The merge request's comment about the approval (or, in Merge Pilot, about the decision it completes) also carries the warning.

What is audited​

ActionWhen
change_approval_voteA vote cast in Merge Pilot (with the decision, the approvals so far and needed, the comment, and the approver a stand-in voted for); an approval in the tracker that did not yet meet the quorum
mr_approvedAn approval met the quorum, in the tracker or in Merge Pilot
change_approval_rejectedA rejection, in the tracker or in Merge Pilot
change_approval_rejection_withdrawnA rejection was withdrawn (with the voter, the reason and the status after it)
change_approval_decided_after_mr_mergedA merged change's review was decided
change_approval_vote_ineligibleA tracker decision was ignored: the person may not decide this change (an author's rejection included)
change_approval_self_approval_blockedThe author's own approval in the tracker was ignored
change_approval_assign_me, change_approval_taken_overSomeone took the change approval, or took it over. A failure is recorded too
change_approval_approval_revoked, change_approval_approval_revoked_after_mergeThe approval was withdrawn in the tracker, before or after the merge
change_approval_sync_failedMoving the change approval in the tracker after a decision failed
approval_fatigue_detectedThe fatigue warning was raised
delegation_created, delegation_deletedA stand-in was set up or ended

The full list is in the Audit log.

API​

ActionRequest
VotePOST /api/v1/merge-requests/{id}/votes with decision (approve or reject) and comment (required to reject, at least 5 characters once trimmed; at most 2,000 characters). A person only: a session or a personal API token. Answers the updated merge request
Withdraw a rejectionPOST /api/v1/merge-requests/{id}/rejection/withdraw with voter (default: the caller) and reason (at least 5 characters). A person only. Answers the updated merge request
Take the change approvalPOST /api/v1/merge-requests/{id}/assign-me, answers assignee
Read where it standsGET /api/v1/merge-requests/{id}: approval.groups[] (each way and its requirements[] with required and approvers), approval.votes[] (voter, decision, source, comment, cast_by, cast_by_id, fills, change_approval_key, at), approval.approved, approval.fatigue[] (one warning per approver), and issue_tracker.change_approval_key, change_approval_status, change_approval_assignee, assignment_problem, sync_error

A vote answers 403 when you may not vote (the reason is in the message), 409 when there is nothing to vote on (the merge request is closed, the change approval is decided, the repository is watched, or the change is standard), and 400 for a rejection whose reason is shorter than 5 characters.

Video tutorials

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

Approve, Reject and Withdraw in Merge PilotYouTube ↗
Only Eligible People Decide in JiraYouTube ↗