What happens when…
A merge request does not always travel the straight path from opened to approved to merged. This page follows each common detour and says what Merge Pilot does, in order: to the merge request, to its change approval in the tracker, to the merge gate, and in the audit log. The straight path itself is described in Merge requests, the gate in Merge gate and the change approval in Change approval.
Throughout, the periodic re-check is Merge Pilot's regular pass over open merge requests that are still waiting on something. It reads back what a lost webhook would have told it (CI runs, tracker decisions, merges and closes), retries what failed and evaluates the merge request again.
New commits are pushed
Every decision is for the merge request's latest commit. When new commits arrive:
- The merge request is processed again: the policy is matched again, the scans the policy runs start for the new commit, risk is assessed again (an accepted risk no longer applies), work items are read again.
- The gate goes back to waiting until the controls pass for the new commit.
- The change approval follows the policy's New commits after a change approval (Lifecycle tab):
| Setting | The change approval | Votes | Tracker | Merge request comment | Audit |
|---|---|---|---|---|---|
| Open a new change approval (default) | The old one is retired and listed under Earlier change approvals as superseded; a new one is opened for the new commit and linked to the old one | Gone with the old change approval | The old one gets Merge Pilot: this change approval no longer covers the merge request because new commits were pushed (…). A new change approval will be created for the updated change; do not approve this one. An old one that was still undecided also moves to the tracker's cancelled status, when the connection has one | change approval … no longer applies because new commits were pushed (…). Any approval based on it was withdrawn. … | change_approval_superseded, then change_approval_created |
| Reopen the change approval | The same one goes back to the tracker's reopen status, now covering the new commit; listed as reopened | Cleared | Merge Pilot: reopened because new commits were pushed (…). Review the updated merge request and approve again. | change approval … was reopened because …. The merge request needs its approval again. | change_approval_reopened |
| Keep the approval while the change is the same | Kept 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 gone with the old one | As the outcome | As the outcome | change_approval_new_commits_kept, or as Open a new change approval |
| Keep the approval | Kept, and now covers the new commit | Kept | Nothing | Nothing | change_approval_new_commits_kept |
- Reopen the change approval needs the tracker connection's reopen status. Without one, or when the move fails, a new change approval is opened instead.
- A change approval that was rejected (or cancelled) is always replaced by a new one when new commits arrive, whatever the setting: reworking a rejected change starts its approval again.
- An approval made in the tracker for the old commit, arriving after the push, waits until the push has been processed and then applies to the change approval as it now is; an approval made before a reopen is ignored.
- If new commits arrive while the change approval is still being opened, the change approval is opened for the latest commit.
The target branch is changed
An approval into one branch is not an approval into another.
Retargeted to another branch Merge Pilot follows:
- The merge request is processed again under the policy that matches the new branch.
- Its open or approved change approval is retired (its target branch changed (main → release/1)), the merge request says so, and a new change approval is opened when the new policy needs one. When it does not, the old one is retired without a replacement (No new change approval will be created). A rejected change approval stays rejected until new commits arrive or the merge request is reopened.
- The gate waits again.
Retargeted to a branch Merge Pilot does not follow (outside the company's or project's branch patterns):
- The merge request leaves change management. Its page says This merge request now targets
sandbox, which change management does not cover. It is no longer gated; retarget it to a covered branch to bring it back.mr_out_of_scopeis written. - An undecided change approval is cancelled: it gets Merge Pilot: … now targets …, which change management does not cover; this change approval is no longer needed., moves to the tracker's cancelled status, and
change_approval_cancelledis written. An approved or rejected one keeps its decision. - Merging it into that branch is not a violation.
Retargeted back into a followed branch: it is gated again from the start, with a new change approval. If it is merged into a followed branch before Merge Pilot has processed the retarget, the merge counts as a merge without approval (below).
A merge request that was left ungated when its repository moved to change management is gated once it is retargeted.
A change freeze begins or ends
Freezes are set on the company's Change calendar; how they act is described in Change freezes.
When a freeze that holds merges begins (Hold merges, or Emergency changes only for a change that is not an emergency):
- While a freeze is in force, the periodic re-check also looks at open merge requests whose gate is already open, so no event is needed.
- The Change freeze line of the decision fails (Change freeze … until …: merges are held.) and the gate closes, even for a change already approved. A policy marked Exempt from change freezes is not held; under a policy with Let one held change go ahead during a freeze, someone it allows can select Release from the freeze on the merge request to let its current commit go ahead (
freeze_release; see Change freezes). - Approvals go on: the change approval can still be opened and decided during the freeze.
- While risk assessment is on, every change assessed during any freeze scores critical.
When it ends, the next re-check evaluates the held merge requests again and opens the gate of those whose controls pass.
A merge during the freeze (the VCS gate bypassed, and not of a commit released from it) is recorded as non-compliant: the page shows This change was merged during the change freeze "…", which held it. It is recorded as non-compliant., mr_merged_in_freeze is written and the Merged during a change freeze notification is sent. In a watched repository nothing was held: the page says the freeze would have held it (Would be blocked (watched): …), with no audit entry or notification.
An emergency is declared
- A change becomes an emergency when an emergency policy covers it, usually because of a label such as
emergency. Whoever added the label declares it; for a policy that matches on something else, the author does. - The company's emergency rules (or the policy's own) are checked: who may declare one (Anyone who may label the change, or one approver pool), whether the author may declare their own change, and the limit of emergencies per repository in a number of days. When a rule is 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 as usual. See Who may declare an emergency.
- The declaration is recorded on the merge request (Declared an emergency by … (label "…", …): policy … lets it merge before it is approved., plus The author declared it. when so), written as
emergency_declared, and sent as the Emergency declared notification. - The approval does not hold the merge: the gate opens once the other controls pass. A change freeze in Emergency changes only mode lets it through.
- A change approval is opened for the review afterwards, once the work items check out and no risk hold applies. The Issue tracker card shows Emergency change: review due …; the deadline is the policy's Review deadline (72 hours by default) from when the change approval is opened.
- Approvers review it in Merge Pilot (Approve and Reject on the Approval card) or in the tracker, before or after the merge. The review takes the same checks as any change approval decision: the author never decides it, only the policy's approvers count, it needs the policy's number of approvals, and the company's tracker approval settings apply; a decision that does not count is undone in the tracker and explained on the merge request. Once decided after the merge, Merge Pilot records the decision and who made it (
change_approval_decided_after_mr_merged), with themr_approvedorchange_approval_rejectedentry, the notification and a comment on the merge request. - If the review is not decided by the deadline:
emergency_review_overdue, the Emergency review overdue notification, a comment on the change approval (Merge Pilot: this emergency change was not reviewed by its deadline. Review and approve or reject it now.), and the card shows Emergency change: review was due …. This happens once per change approval. - If the change merged before its review change approval could be opened (for example while the tracker was down), the periodic re-check opens it afterwards, for emergency changes merged within the last 30 days.
The change approval is rejected
A rejection comes from Reject in Merge Pilot (with a reason) or from a move to the tracker's rejecting status. The policy's When rejections reject decides when the change approval is rejected: by default one rejection is enough; with Every approval group has a rejection from one of its approvers or More people reject than approve, a rejection is recorded and the change approval is not rejected until the rejections meet that rule (see Rejections).
- The change approval is Rejected; the approval control fails (KEY was rejected.) and the gate is blocked.
- The merge request gets a comment (change approval … was rejected by …),
change_approval_rejectedis written and the Change approval rejected notification is sent, wherever the rejection was made. A rejection in Merge Pilot also writeschange_approval_votewith the reason and comments the reason on the change approval in the tracker. - The author's My Work lists the change with Change approval rejected.
- Then the policy's Missing work items or a rejected change approval applies:
- Block until fixed (default): the merge request stays open and cannot merge.
- Close the merge request: Merge Pilot comments (this merge request was closed by policy …) and closes it;
mr_rejectedis written and the Merge request refused notification is sent. If closing fails, it is tried again after 15 minutes.
- No more votes are taken on a rejected change approval. To go on, push new commits or reopen the merge request: a new change approval is opened. While the merge request is open, whoever rejected or a company admin can also Withdraw the rejection with a reason (unless the policy turns that off): the change approval is decided again from the remaining votes, the tracker follows and
change_approval_rejection_withdrawnis written.
The approval is withdrawn
Someone moves an approved change approval in the tracker out of its approving status (to any status but a rejecting one; a move to a rejecting status is a rejection, above). Merge Pilot's own moves do not count. The move counts only when made by someone who may decide the change approval (an approver of the change under the company's tracker approvals setting, never its author) or a company or platform admin, in Jira and in the built-in tracker; anyone else's move is undone (the change approval goes back to its approving status, change_approval_vote_ineligible is written) and the approval stands.
While the merge request is open:
- Every vote on the change approval is cleared, those cast in Merge Pilot included, and it is open again.
- The merge request gets change approval … was moved out of its approved status, so the approval was withdrawn. The change waits for approval again.
change_approval_approval_revokedis written and the merge request is evaluated: the gate waits for a new quorum.
After the merge:
- The merge request is flagged: The change approval was withdrawn in the tracker after this change was merged.
change_approval_approval_revoked_after_mergeis written and the Approval revoked after merge notification is sent.
A change approval that is deleted in the tracker or moved to another key is no longer valid: change_approval_lost is written, the merge request is told (… is no longer valid because …. Any approval based on it was withdrawn; a new change approval will be created.) and a new one is opened. When the project's tracker connection changes, the change approval in the old tracker is retired the same way and a new one is opened in the new tracker.
The merge request is closed or reopened
Closed without merging:
- It is recorded as closed.
- An undecided change approval is cancelled: it gets Merge Pilot: … was closed without merging by …; this change will not be deployed., moves to the tracker's cancelled status, and
change_approval_cancelledis written. An approved or rejected change approval keeps its decision. - A decision made in the tracker afterwards is only recorded (
change_approval_decided_after_mr_closed).
Deleted on the VCS: when the VCS no longer has the merge request while its repository is still there, Merge Pilot closes it (in watched repositories too), with unknown (deleted on the VCS) as who closed it, and writes mr_deleted_on_vcs. An undecided change approval is cancelled as above, with Merge Pilot: … was deleted; this change will not be deployed.
Reopened: it is processed as a new event. A cancelled or rejected change approval is replaced by a new one; an approved change approval for the same commit still stands. A merge request closed before its change approval was opened gets one when it is reopened.
It is merged without Merge Pilot's approval
The VCS gate normally prevents it, but an administrator can bypass it. When the VCS reports a merge, Merge Pilot compares it with its last decision for the merged commit and target branch:
| What happened | Recorded as | On the merge request page | Notification |
|---|---|---|---|
| Merged while the decision was not approved, or approved for an earlier commit only | mr_merged_without_approval | This change was merged in <GitLab or GitHub> before change management approved it. It is recorded in the audit log. | Merged without approval |
| Merged during a freeze that held it | mr_merged_in_freeze | The freeze banner (above) | Merged during a change freeze |
| Merged by someone who approved it, when the policy flags or forbids it | mr_sod_flag or mr_sod_block | Separation of duties: … or Separation of duties broken: … | For a forbidden one, Separation of duties broken |
| GitHub marked the pull request merged because its commits reached the branch another way | mr_merged_through_other: fine when every pull request that brought them was approved; otherwise (for example a direct push) also a merge without approval | Merged without approval when it counts as one | |
| A watched repository's merge that change management would have held | mr_merged_would_have_blocked | Change management would have held this merge: it merged while its decision was not approved. | None |
In every case mr_merged is written, and the change approval gets Merge Pilot: … was merged by …. (with WARNING: it was merged before this change approval was approved. when so) and moves to the tracker's merged status. A merge whose webhook was lost is found by the periodic re-check or by Sync with <GitLab or GitHub> on the Merge requests page; it is then recorded with unknown (missed webhook) or unknown (found by state sync) as who merged.
A change approval still undecided at the merge (a late decision on a change merged without approval) is decided afterwards like an emergency change's review: in Merge Pilot or in the tracker, under the same checks. The decision is kept on the merge request with who made it (change_approval_decided_after_mr_merged); the merge's flags stay. A decision on a change approval already decided is only recorded.
A merge queue or merge train is used
- GitHub merge queue: for each merge group, Merge Pilot reports its Merge Pilot / change approval check on the group's commit. It passes only when change management approved the pull request at the commit it was queued with; otherwise it fails (Change management has not approved the pull request at the commit it was queued with.), so the queue never merges what was not approved. Watched repositories get no check. Each check is written as
merge_group_checked. See GitHub → Merge queue. - GitLab merged results and merge trains: their pipelines run on a merge commit of the latest commit into the target branch and count for the latest commit in the CI control (see CI).
A change approval waits a long time
Merge Pilot does not close or expire change approvals because of their age. An open change approval stays open until it is decided, replaced (new commits, retarget, a lost or moved issue, a new tracker), or cancelled because the merge request was closed or left change management. What does run on old work:
- the periodic re-check keeps reading the tracker for decisions whose webhook was lost;
- a change approval nobody could be assigned is given to the first person who may take it, when the company or policy says Assign it as soon as someone can;
- with a change approval deadline set, Change approval due soon is sent when the deadline is near and Change approval overdue once a normal change's change approval passes it undecided; it stays open;
- an emergency review past its deadline is reported once (above).
The VCS or the tracker is unavailable
Work is done by background jobs (see Jobs). A job that fails because a system cannot be reached is retried automatically, with a growing wait; a VCS rate limit makes it wait without counting as a failure. When its last attempt fails, job_failed is written and the Background job failed notification is sent; the periodic re-check later recovers the lost work.
The VCS cannot be reached:
- Events are not processed and the gate cannot be written until it is back. A decision whose gate could not be written is written again by a later evaluation or the periodic re-check.
- During a re-check, a VCS connection that fails is skipped for the rest of that run.
- A scan that cannot read the merge request fails, never passes, and is retried or waits for a re-scan as the company's scan settings say (see Re-running checks).
The tracker cannot be reached:
| When | What happens |
|---|---|
| Opening the change approval | The approval control is blocked: The change approval could not be created (…); it is retried automatically. The periodic re-check tries again, first after one re-check interval, then after a pause that doubles each time, up to 6 hours. Resync tries at once. A creation that keeps failing for the same reason is reported once. An emergency change is not held: it may merge, and its review change approval is opened once the tracker is back |
| A vote in Merge Pilot | The vote is recorded and counts at once. Only the move in the tracker fails: the page shows The change approval is out of step with this page. … Move it in the tracker by hand, or fix the tracker connection's statuses and transition paths. and change_approval_sync_failed is written. The periodic re-check retries the move up to 5 times; after that it stays on the page until someone moves the change approval by hand or selects Resync |
| A decision made in the tracker | When the webhook is lost, the periodic re-check reads the change approval's latest status and applies the decision |
| Comments on the change approval | Best effort: a comment that fails is not retried |
| After a merge or close | The change approval's move to the merged or cancelled status is retried by the periodic re-check up to 5 times, and by Resync on the merge request at any time |
Related pages
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →