Skip to main content
3 video tutorials

Change approval lifecycle

A change approval is the tracker issue that records the decision on one change. Merge Pilot opens it in the tracker linked to the repository's VCS connection (Jira or the built-in tracker), assigns it to someone who may decide it, follows its status, and moves it on when the merge request merges or closes. This page follows a change approval through its life. Who must approve, who may vote and how votes are counted are on Approval.

The change types​

Change typeChange approvalEffect on the merge gate
NormalOpened once the change is ready for review (below)The gate waits until the change approval is approved, and is blocked when it is rejected
EmergencyOpened for a review afterwards, due within the policy's Review deadlineNone: the change merges once its other controls pass. An emergency change that merged before its change approval existed still gets one
StandardOnly when the policy's Open a change approval as a record is on, as a recordNone: pre-approved. Nobody votes on it
Refused (a policy that refuses its changes)NoneBlocked by the policy itself

When one is opened​

For a normal change, a change approval is opened when all of these hold:

  • the repository is under change management (never for a watched one: No change approval is opened while the repository is watched.);
  • a tracker is linked to the VCS connection (otherwise No issue tracker is configured for this project, so the change cannot be approved.);
  • the enforced work items check out and no risk hold applies (until then: A change approval is opened once the work items check out and no risk hold applies; CI and scans can still run.);
  • enough people may approve it (otherwise Only N people may approve this change, …; see Approval);
  • the merge request has no change approval that still covers its latest commit.

CI and scans need not have finished: the change approval is opened while they run.

An emergency change's review change approval, and a standard change's record, are opened under the same conditions, except that the number of people who may approve does not matter. An emergency change does not wait for it: it may merge as soon as its other controls pass.

Merge Pilot asks for one change approval per commit. Before creating it, it reads the merge request again: when it was closed meanwhile no change approval is opened, and when new commits arrived meanwhile the merge request is processed again first. A merge request closed or moved out of scope while its change approval was being created gets that change approval cancelled at once.

While it is being created, the Change approval line says Creating the change approval. and the clearance track Creating change approval.

When creation fails​

The Change approval line says The change approval could not be created (…); it is retried automatically., and the gate is blocked (an emergency change can still merge: Emergency change: may merge now; creating the review change approval failed (…), retrying.). The periodic re-check tries again after a pause that starts at the re-check interval and doubles with each failure in a row, up to 6 hours. Resync on the merge request tries again at once. Saving the tracker connection's settings also has the failed ones tried again at the next check.

Where it is opened​

In the tracker linked to the merge request's VCS connection (see VCS connection settings), in the tracker settings' Project with its Issue type. A repository can name its own project, issue type or link type on its page (see Project page).

What it contains​

PartContent
SummaryThe Summary template of the tracker settings (see Templates). Without a template: the change type, the policy's priority when it is not normal, the repository's path, the merge request's reference and its title, for example Normal change: acme/payments !42 Add the login page (at most 255 characters)
DescriptionThe Description template. Without one: a Change Management Record with the project, the merge request (as a link), source and target branch, author, title and the work items (listed once). Merge Pilot adds a last line, Merge Pilot reference: …, by which it finds the issue again if the tracker's answer to the creation was lost; a duplicate created that way is commented and moved to the Cancelled status
Custom fieldsThe Custom fields of the tracker settings, with the template variables filled in (see Fields)
Field mappingsValues copied from the linked work items (Field mappings)
Priority (Jira)The Jira priority mapped from the policy's priority (Priorities)
AssigneeSomeone who may decide it, chosen as the policy's Assign the change approval says (see Assignment). When the assignee is deactivated (from the Users list or their Edit user dialog) or moved to another company, the change approval is assigned again or kept with a warning as the company's When an assignee is deactivated says (Approvals tab); when nobody else may take it, it is also unassigned in the tracker, with a comment
CreatorThe tracker connection's account, or the author of the merge request when the company asks for it (see Who creates the change approval)
Links (Jira)Linked with the Link type to the merge request's work items and to the change approval it replaces, if any
Built-in trackerA link to the merge request and the commit it covers

The template variables include the change type ({{change_type}}), the policy's priority ({{priority}}) and the merge request's risk level ({{risk_level}}).

Once it is created, Merge Pilot:

  • comments on the merge request: change approval created: KEY, the work items, and Next steps for the change type (for a normal change, how many approvals are needed and what a rejection does; for an emergency change, the change approval must be reviewed within N hours; for a standard change, pre-approved; the change approval is a record only);
  • sends the Change approval created notification;
  • writes change_approval_created;
  • evaluates the merge request, whose Change approval line now waits for the votes (Waiting for KEY to be approved.).

For an emergency change the review due time is set when the change approval is created: its creation time plus the policy's Review deadline.

Statuses​

In Merge Pilot a change approval is in one of four statuses (the merge request's issue_tracker.change_approval_status):

StatusMeaningMerge gate (normal change)
openWaiting for a decision, or for more approvalsWaits
approvedApproved: the policy's approvals are metThe Change approval control passes (KEY approved.)
rejectedRejected, in the tracker or in Merge Pilot, as the policy's When rejections reject says (by default one rejection rejects it)Blocked (KEY was rejected.)
cancelledThe merge request was closed without merging, or left change management, before a decisionNot applicable: nothing is waiting

How tracker statuses map​

In the trackerBecomes
Moved to a closing status (Jira) or a closing state of the tracker project (built-in tracker)An approval by whoever moved it. When the policy's approvals are met the change approval is approved (mr_approved, notification Change approval approved). When more are needed, the approval is counted and the change approval goes back to the Reopen status for the next approver (change_approval_vote)
Moved to a rejection status (Jira) or a rejecting state (built-in tracker)A rejection: rejected (change_approval_rejected, notification Change approval rejected) once the rejections reject it under the policy's When rejections reject; until then the rejection is recorded and the change approval goes back for a decision (see Rejections)
Moved out of its approving status after being approved, by someone other than Merge Pilot's own accountWhen the person may decide the change approval or is a company or platform admin (anyone else's move is undone: the change approval goes back to its approving status and change_approval_vote_ineligible is written), Revoked: every vote on it is removed, it is open again and waits for a fresh quorum (change_approval_approval_revoked); the merge request gets a comment. After the merge, the merge request is flagged instead (The change approval was withdrawn in the tracker after this change was merged., change_approval_approval_revoked_after_merge, notification Approval revoked after merge)
Deleted, or moved to another keyLost: it is retired (outcome lost), its approval is dropped, change_approval_lost is written and, for an open merge request, a new change approval is opened

Approvals and rejections are checked before they count: the author's own is ignored, and so is one from someone who may not decide the change; the change approval then goes back for a decision. See In the tracker.

Decisions made in Merge Pilot​

Approve and Reject on the merge request's Approval card count like tracker decisions. Merge Pilot comments on the change approval (… approved this change in Merge Pilot (1 of 2 approvals).) and, once it is decided, moves it to the approving or rejecting status: for the built-in tracker the tracker project's own approving or rejecting state, for Jira the first Closing status or Rejection status (or done and rejected when none is set). See In Merge Pilot.

Lost webhooks​

When the tracker's webhook is lost, the periodic re-check reads the open and approved change approvals' latest status change from the tracker and handles it as the webhook would have (see The periodic re-check). Resync on the merge request does it at once.

New commits​

What new commits do to the change approval is the policy's New commits after a change approval (see New commits and failures):

SettingEffect on the change approvalApproval
Open a new change approval (default)Superseded: it moves to the merge request's Earlier change approvals (outcome superseded), Merge Pilot comments on it (… this change approval no longer covers the merge request because new commits were pushed (old → new). A new change approval will be created for the updated change; do not approve this one.) and on the merge request, and a new one is opened for the new commit, linked to the old one in JiraReset: approved from scratch
Reopen the change approvalThe same change approval moves back to the Reopen status, is open again and covers the new commit; Merge Pilot comments on it and on the merge request. Without a reopen status, or when the move fails, a new change approval is opened insteadReset: its votes are cleared
Keep the approval while the change is the sameKept, as Keep the approval, when the lines the change adds and removes are the ones approved (a rebase, a merge of the target branch); otherwise, or when they cannot be compared, as Open a new change approvalKept, or reset
Keep the approvalThe change approval now covers the new commit (change_approval_new_commits_kept)Kept

Whatever the setting:

  • A rejected or cancelled change approval is replaced by a new one when new commits are pushed or the merge request is reopened.
  • An approval in the tracker for older code does not count for the new commit: Merge Pilot first handles the new commits, then the decision.
  • An approval made before the change approval was reopened does not count.
  • Decisions on a superseded change approval are ignored.
  • A superseded change approval that was still undecided (open) is moved to the tracker's Cancelled status, when one is set, as a closed merge request's is. One that was already approved keeps its approving status, unless the Jira connection's Also cancel superseded approved change approvals is on: then it is moved to the Cancelled status too. Its comment then says who approved it and for which commit, that the approval does not apply to the new commits, and whether it stays approved as the record of that approval or was moved to the Cancelled status (the approval stays in its history and in the audit log). One that was rejected keeps its status. When the move fails, the merge request page shows the error on the entry in Earlier change approvals, change_approval_sync_failed is written, and the move is retried in the background (up to 5 times) and by Resync.

Other changes that replace the change approval (outcome superseded, with the reason):

  • the merge request is moved to another target branch: its target branch changed (old → new);
  • the repository's tracker changed: the project's issue tracker changed (the old change approval is left in the old tracker as it is: no comment, no move);
  • the policy that now covers the merge request uses no change approval: policy "…" does not use a change approval. No new one is opened (No new change approval will be created).

Earlier change approvals​

The merge request page lists every change approval the merge request had before (Earlier change approvals), newest first, with the outcome (superseded, reopened, lost), the reason and the date. API: issue_tracker.change_approval_history[] with key, url, status, commit_sha, outcome, reason, at, and for a move to the Cancelled status still owed, sync_move (cancelled), sync_error and sync_error_at.

When the merge request is merged​

Merge Pilot comments on the change approval (Merge Pilot: MR !12 was merged by …; with WARNING: it was merged before this change approval was approved. when it merged without approval) and moves it to the tracker's Merged status, when one is set. The change approval keeps its status in Merge Pilot. See What is flagged at merge.

An undecided change approval (an emergency change's review, or a late decision on an unapproved merge) is still decided after the merge, in Merge Pilot or in the tracker, under the same checks as before it: the author never decides it, only the policy's approvers count, and it takes the policy's number of approvals. Once decided it shows the decision and who made it, the merge request's Approval line shows the decision too (for example Emergency change: reviewed and approved in KEY.), and change_approval_decided_after_mr_merged is written with the usual mr_approved or change_approval_rejected. The merge's flags stay.

An emergency change that merged before its change approval existed (it could not be created in time, or creating it failed) gets its review change approval afterwards, when it merged within the last 30 days.

When the merge request is closed​

  • An undecided change approval (open) is cancelled: Merge Pilot comments on it (… was closed without merging by …; this change will not be deployed.), moves it to the tracker's Cancelled status when one is set, records it as cancelled and writes change_approval_cancelled.
  • An approved or rejected change approval keeps its decision.
  • A decision made in the tracker after the close is written to the audit log only (change_approval_decided_after_mr_closed).

A merge request deleted on the VCS (its repository still answering) is closed the same way, with … was deleted; this change will not be deployed. on its undecided change approval, and mr_deleted_on_vcs is written.

A merge request moved to a target branch change management does not cover is handled like a close (… now targets <branch>, which change management does not cover; this change approval is no longer needed.).

A policy can close a merge request whose change approval was rejected (Missing work items or a rejected change approval → Close the merge request; see Closed by its policy). The rejection is recorded first, so the close does not cancel the change approval.

When the merge request is reopened​

  • A cancelled or rejected change approval is replaced by a new one (outcome superseded, the previous change approval was cancelled or rejected).
  • An approved change approval that still covers the latest commit stays approved: the merge request can merge again once its other controls pass.
  • New commits pushed meanwhile are handled as above.

Tracker moves that fail​

When Merge Pilot cannot move a change approval in the tracker (for example a transition the workflow does not offer, or a tracker connection that cannot be used when a vote in Merge Pilot decides it), the merge request page says The change approval is out of step with this page. Moving KEY to "…" failed: … (or Moving KEY to the tracker's approving status failed: …, or its rejecting, merged, cancelled or reopen status, when the status could not be worked out), and change_approval_sync_failed is written. The periodic re-check tries the move again, up to 5 times; after that the message stays until someone moves the change approval by hand, or fixes the tracker connection's statuses or Transition paths and selects Resync (which tries again, also for a merged or closed merge request). Each try goes to the status the connection's settings name at that time: after a status is corrected, the move goes to the corrected one; when the status is no longer set (for example the Merged status is cleared), nothing is owed any more and the message goes away. Until the move is made, the tracker's status is not taken for a decision.

API​

  • GET /api/v1/merge-requests/{id}: issue_tracker holds change_approval_key, change_approval_url, change_approval_status, change_approval_assignee, assignment_problem, change_approval_created_at, change_approval_commit_sha (the commit it covers), change_approval_history, change_approval_error, review_due_at, review_overdue_at, decided_after_merge, decided_by, sync_error, work_items, work_item_problems; approval holds the votes and the approval groups; approval_revoked_after_merge flags a revocation after the merge.
  • POST /api/v1/merge-requests/{id}/votes (decision, comment), POST /api/v1/merge-requests/{id}/rejection/withdraw (voter, reason) and POST /api/v1/merge-requests/{id}/assign-me.
  • POST /api/v1/merge-requests/{id}/resync.
  • The tracker settings that shape the change approval: PUT /api/v1/connections/{id}/tracker-settings (see Jira).

Audit log​

ActionWhen
change_approval_createdA change approval was opened
change_approval_vote, mr_approved, change_approval_rejectedA vote was counted; the change approval was approved; it was rejected
change_approval_rejection_withdrawnA rejection was withdrawn in Merge Pilot
change_approval_vote_ineligible, change_approval_self_approval_blockedA decision was ignored
change_approval_superseded, change_approval_reopened, change_approval_new_commits_keptWhat new commits (or a new target branch, tracker or policy) did to it
change_approval_lostIt was deleted or moved in the tracker
change_approval_approval_revoked, change_approval_approval_revoked_after_mergeIts approval was withdrawn in the tracker
change_approval_cancelledThe merge request closed or left change management before a decision
change_approval_decided_after_mr_merged, change_approval_decided_after_mr_closedA decision came after the merge request's outcome
change_approval_sync_failedMoving it in the tracker failed
change_approval_assigned, change_approval_assign_me, change_approval_taken_overIt was assigned, taken or taken over

See also the Audit log.

Video tutorials

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

Follow One Merge Request Through the GateYouTube ↗
New Commits After an ApprovalYouTube ↗
Stand-Ins for Approvers Who Are AwayYouTube ↗