Skip to main content
2 video tutorials

Merge gate

The merge gate is how GitLab or GitHub itself keeps a merge request from merging until its change policy is met. After each evaluation Merge Pilot sets the gate for the merge request's latest commit: a new commit, or a new target branch, needs a new decision before it can merge.

For a short overview of what it is for, see the Merge gate feature page.

The gate only exists for repositories under change management. For a watched repository nothing is written to the VCS (see Watched repositories).

The decision​

Each evaluation runs the policy's controls and takes one of three gate states (see Controls):

Gate (label in Merge Pilot)WhenAPI value
Can mergeEvery enforced control passedapproved
WaitingNo enforced control failed, but at least one is still pending: a scan running, CI not finished, work items being looked up, the change approval being opened or waiting for votespending
BlockedAt least one enforced control failed: a check failed, a risk hold, a change freeze, a rejected change approval, too few approvers, or a policy that refuses the changeblocked

Report-mode controls never change the gate. A standard change's approval passes at once (Standard change: pre-approved.); an emergency change's review is never enforced, so it can merge as soon as its other controls pass.

The gate's title is the first enforced control that failed, or the first one still pending, with the first sentence of its reason (for example CI: Failed: build.). Otherwise it is Approved by change management, Blocked by change management or Waiting for change management.

GitLab​

On GitLab the gate is an approval rule whose only approver is the connection's bot user, on protected target branches (written by the setup steps, see GitLab):

DecisionWhat Merge Pilot does in GitLab
Can mergeThe bot user approves the merge request, for the commit the decision is for. GitLab refuses that approval when the merge request has moved on to another commit
Waiting, BlockedThe bot user withdraws its approval, if it gave one

Without the bot's approval the rule Merge Pilot — <branch> is not met and GitLab does not let the merge request merge. Nobody else can meet the rule.

  • With the setup step Remove approvals when commits are added (on by default), GitLab removes the bot's approval as soon as a commit is pushed. When that step is turned off, the approval stays until Merge Pilot has evaluated the new commit and withdrawn it.
  • Waiting and Blocked look the same in GitLab: the approval is missing. The difference, and the reason, is in Merge Pilot and in the status comment.

GitHub​

On GitHub the gate is the check Merge Pilot / change approval, which the connection's GitHub App reports as a check run on the pull request's head commit. The ruleset Merge Pilot change management requires it on the target branches, accepted from the App only, so no other App or person can satisfy it (see GitHub).

DecisionCheck run
Can mergeCompleted, conclusion success
WaitingIn progress
BlockedCompleted, conclusion failure

The check run's title is the gate's title; its summary is the decision checklist (the policy, then one line per control, as in the status comment). Each decision is a new run, and GitHub counts the latest run per commit. A new commit has no check yet, so GitHub holds it until Merge Pilot reports one.

The status comment​

Merge Pilot keeps one comment on the merge request up to date with the decision: a headline (this merge request can merge., is waiting on the items below., cannot merge yet., or cannot merge: its policy refuses it. under a Refuse policy), the policy, one line per control and the commit it is for. See The status comment.

Merge Pilot also comments when a change approval is opened, decided, superseded, reopened or lost, and when it closes a merge request (below).

When the gate is set again​

The gate and the status comment are written when the decision changes: another commit, another target branch, another gate state, or a control whose status or reason changed. An evaluation that changes nothing writes nothing to the VCS.

Merge Pilot evaluates a merge request again when something it depends on changes:

What happenedWhat Merge Pilot does
The merge request is opened or reopenedThe policy is matched, the policy's scans start, risk is assessed, work items are looked up, then the merge request is evaluated
New commits are pushedAs above, for the new latest commit. Until the scans and CI of the new commit are known, enforced controls are pending and the gate waits. What happens to the change approval is the policy's New commits after a change approval (see Change approval)
The target branch is changedAs above. The change approval is replaced: an approval into one branch is not one into another. A branch change management does not cover takes the merge request out of scope (below)
Labels, title, description or draft state changeThe policy is matched again (a label can make a change an emergency, for example), work item keys are read again, and the merge request is evaluated
A CI run starts, changes or finishesThe run is recorded and the merge request evaluated
A code review is given or withdrawnEvaluated again
A scan finishes, or someone selects Re-scanEvaluated again when the scan finishes
A vote is cast in Merge Pilot, or a risk is acceptedEvaluated again
The change approval changes in the tracker: approved, rejected, moved out of its approved status, deleted or moved to another keyThe decision is recorded, then the merge request is evaluated (see Change approval)
A change policy is created, edited, deleted or reorderedEvery open merge request of the VCS connection is evaluated again, in the background (see Open merge requests after a change)
A change freeze starts or ends at its scheduled timePicked up by the periodic re-check (below)
The company's risk settings, change freezes or change windows are saved (or the reviewed change is approved)Every open merge request of the company is evaluated again at once, in the background, as after a policy change
Someone selects Resync on the merge requestThe periodic re-check, at once (see Merge requests)

GitLab reports every edit of a merge request as an update; on GitHub, the pull request actions that lead to an evaluation are opened, reopened, synchronize, ready_for_review, converted_to_draft, labeled, unlabeled, and edited when the base branch, title or description changed.

The periodic re-check​

The re-check runs every 10 minutes by default. Each run takes up to 200 open merge requests, oldest decision first, that were not evaluated since the previous run and that:

  • cannot merge yet, or have a change approval that is open or approved;
  • have a change approval that could not be opened (retried after a pause that doubles with each failure, up to 6 hours);
  • have a decision the VCS never received;
  • belong to a company with a change freeze in force, or whose risk depends on the time (change windows, or a blackout in force).

For each, it reads the CI runs of the latest commit and the change approval's status in the tracker again (as if a lost webhook had arrived), retries a tracker move that failed, and processes the merge request again. So a freeze that starts closes the gate of merge requests that could merge, and one that ends lets them through again, at the next re-check after the freeze starts or ends; a merge request evaluated during the last interval is taken at the run after.

The same run assigns change approvals that nobody could be assigned (where the policy or the company says so), asks for the review change approval of emergency changes that merged without one (merged in the last 30 days), and, every 6 hours for each, looks up whether watched open merge requests were merged or closed.

Watched repositories​

For a watched repository the decision is recorded only: no approval, no check run, no comment, no change approval, nothing closed. Merge Pilot shows what change management would have done (Would pass (watched), Would wait (watched), Would be blocked (watched)) and records mr_watched_approved, mr_watched_pending or mr_watched_blocked. See Watching repositories.

When a repository moves to change management and its open merge requests are let through until their next commit (see What happens to the open merge requests), each of those gets a passing gate, titled Not gated: opened before change management. From its next commit, or when its target branch changes, it is gated like any other.

Moved to another target branch​

A merge request moved to a branch that change management does not cover (not one of the target branch patterns, or an excluded branch) leaves change management: its state becomes Out of scope, an undecided change approval is cancelled (… now targets <branch>, which change management does not cover; this change approval is no longer needed.), and mr_out_of_scope is written. Moved back to a covered branch, it is processed again from the start.

When the VCS gate still covers an excluded branch (on GitLab the approval rule covers the whole branch pattern), Merge Pilot approves a merge request into it so the exclusion is not held by the gate: the gate passes, titled Not checked: excluded branch, and when the merge request is opened, reopened or retargeted into that branch it gets the comment Merge Pilot does not check changes into <branch>: the branch is excluded for this repository. Merge Pilot approved this MR so that its approval rule does not hold it. (PR on GitHub)

Closed by its policy​

A policy whose Missing work items or a rejected change approval is Close the merge request closes the merge request when its enforced work items fail (with a tracker configured) or its change approval is rejected. Merge Pilot comments (this merge request was closed by policy <name>: <reason>) and closes it; when closing fails, it is tried again at a later evaluation, at the earliest 15 minutes after the failed attempt. Recorded as mr_rejected, with the notification Merge request refused. Watched merge requests are never closed. See Change policies.

Merge queues and merge trains​

GitHub merge queue​

When a pull request enters GitHub's merge queue, GitHub asks for the required checks on the merge group's commit. Merge Pilot answers with the Merge Pilot / change approval check on that commit:

SituationCheckSummary
Change management approved the pull request at the commit it was queued withsuccess, Change approvedChange management approved the pull request at the commit it was queued with.
The pull request is not known to Merge Pilotfailure, Change not approvedMerge Pilot does not know this pull request.
Its last decision is for another commitfailureThe pull request was queued with a commit change management has not decided on.
Its last decision is not Can mergefailureChange management has not approved the pull request at the commit it was queued with.

So the queue never merges what change management did not approve. Watched repositories get no check. Each answer is recorded as merge_group_checked.

GitLab merge trains​

Merge Pilot does nothing of its own for merge trains: the gate is the bot user's approval of the merge request. The pipelines GitLab runs on a merge request's merged result or merge train (the refs/merge-requests/<number>/merge and /train refs) run on a merge commit of the latest commit; Merge Pilot counts them for that latest commit, so the CI control sees them.

What is flagged at merge​

Merging cannot be stopped from outside the VCS, so Merge Pilot records what merged and flags what should not have:

FlagWhenAudit actionNotification
Merged without approvalThe last decision did not open the gate for the commit that merged into that branch. The change approval gets a comment: … WARNING: it was merged before this change approval was approved.mr_merged_without_approvalMerged without approval
Merged in a change freezeMerged during a freeze that holds merges (or an emergency-only freeze, for a change that is not an emergency)mr_merged_in_freezeMerged during a change freeze
Would have been held by a freezeThe same, for a watched merge request: nothing held it, so it is not non-compliant (would_have_held_in_freeze)NoneNone
Approver mergedSomeone who approved the change merged it, and the policy flags or forbids itmr_sod_flag, mr_sod_blockSeparation of duties broken, for a forbidden one
Would have been heldA watched merge request merged while its decision was not Can mergemr_merged_would_have_blockedNone
Merged another wayIts commits reached the target branch without the merge request being merged; it counts as merged, and as approved only when they came through other approved merge requestsmr_merged_through_otherNone

Every merge is also recorded as mr_merged and the merge request's change approval is moved on (see When the merge request is merged). A merge request merged out of scope, into a branch change management does not cover, is not flagged.

API​

  • GET /api/v1/merge-requests/{id}: the decision field holds the latest decision: head_sha and target_branch it is for, gate (approved, pending, blocked), controls[] (control, status, blocking, reason), evaluated_at, gate_set (the VCS received it), needs_change_approval, monitored (watched: recorded only).
  • merged_without_approval, merged_in_freeze (the freeze's name), would_have_held_in_freeze (the same, for a watched merge request), would_have_blocked, sod_flags, sod_violation record the merge flags.
  • POST /api/v1/merge-requests/{id}/resync runs the re-check for one merge request.

Audit log​

ActionWhen
mr_policy_matchedA policy (or another version of it) now covers the merge request
mr_gate_approved, mr_gate_pending, mr_gate_blockedThe gate was set to Can merge, Waiting or Blocked
mr_watched_approved, mr_watched_pending, mr_watched_blockedA watched merge request's decision changed (nothing was written)
merge_group_checkedA GitHub merge queue group was answered
mr_rejectedThe policy closed the merge request
mr_out_of_scopeThe merge request moved to a branch change management does not cover
mr_merged, mr_merged_without_approval, mr_merged_in_freeze, mr_merged_would_have_blocked, mr_merged_through_other, mr_sod_flag, mr_sod_blockA merge and its flags

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 ↗
What Developers See in GitLabYouTube ↗