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 type | Change approval | Effect on the merge gate |
|---|---|---|
| Normal | Opened once the change is ready for review (below) | The gate waits until the change approval is approved, and is blocked when it is rejected |
| Emergency | Opened for a review afterwards, due within the policy's Review deadline | None: the change merges once its other controls pass. An emergency change that merged before its change approval existed still gets one |
| Standard | Only when the policy's Open a change approval as a record is on, as a record | None: pre-approved. Nobody votes on it |
| Refused (a policy that refuses its changes) | None | Blocked 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).
- Jira: see How a change approval moves through Jira.
- Built-in tracker: see How change approvals are created and decided.
What it contains
| Part | Content |
|---|---|
| Summary | The 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) |
| Description | The 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 fields | The Custom fields of the tracker settings, with the template variables filled in (see Fields) |
| Field mappings | Values copied from the linked work items (Field mappings) |
| Priority (Jira) | The Jira priority mapped from the policy's priority (Priorities) |
| Assignee | Someone 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 |
| Creator | The 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 tracker | A 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):
| Status | Meaning | Merge gate (normal change) |
|---|---|---|
open | Waiting for a decision, or for more approvals | Waits |
approved | Approved: the policy's approvals are met | The Change approval control passes (KEY approved.) |
rejected | Rejected, 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.) |
cancelled | The merge request was closed without merging, or left change management, before a decision | Not applicable: nothing is waiting |
How tracker statuses map
| In the tracker | Becomes |
|---|---|
| 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 account | When 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 key | Lost: 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):
| Setting | Effect on the change approval | Approval |
|---|---|---|
| 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 Jira | Reset: approved from scratch |
| Reopen the change approval | The 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 instead | Reset: its votes are cleared |
| Keep the approval while the change is the same | Kept, 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 approval | Kept, or reset |
| Keep the approval | The 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_failedis 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 ascancelledand writeschange_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_trackerholdschange_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;approvalholds the votes and the approval groups;approval_revoked_after_mergeflags a revocation after the merge.POST /api/v1/merge-requests/{id}/votes(decision,comment),POST /api/v1/merge-requests/{id}/rejection/withdraw(voter,reason) andPOST /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
| Action | When |
|---|---|
change_approval_created | A change approval was opened |
change_approval_vote, mr_approved, change_approval_rejected | A vote was counted; the change approval was approved; it was rejected |
change_approval_rejection_withdrawn | A rejection was withdrawn in Merge Pilot |
change_approval_vote_ineligible, change_approval_self_approval_blocked | A decision was ignored |
change_approval_superseded, change_approval_reopened, change_approval_new_commits_kept | What new commits (or a new target branch, tracker or policy) did to it |
change_approval_lost | It was deleted or moved in the tracker |
change_approval_approval_revoked, change_approval_approval_revoked_after_merge | Its approval was withdrawn in the tracker |
change_approval_cancelled | The merge request closed or left change management before a decision |
change_approval_decided_after_mr_merged, change_approval_decided_after_mr_closed | A decision came after the merge request's outcome |
change_approval_sync_failed | Moving it in the tracker failed |
change_approval_assigned, change_approval_assign_me, change_approval_taken_over | It was assigned, taken or taken over |
See also the Audit log.
Related pages
- Approval: who approves, votes, separation of duties, emergency reviews, assignment.
- Jira and Built-in tracker: tracker settings, statuses and templates.
- Merge gate and Merge requests.
- Change policies.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →