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) | When | API value |
|---|---|---|
| Can merge | Every enforced control passed | approved |
| Waiting | No 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 votes | pending |
| Blocked | At 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 change | blocked |
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):
| Decision | What Merge Pilot does in GitLab |
|---|---|
| Can merge | The 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, Blocked | The 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).
| Decision | Check run |
|---|---|
| Can merge | Completed, conclusion success |
| Waiting | In progress |
| Blocked | Completed, 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 happened | What Merge Pilot does |
|---|---|
| The merge request is opened or reopened | The 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 pushed | As 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 changed | As 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 change | The 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 finishes | The run is recorded and the merge request evaluated |
| A code review is given or withdrawn | Evaluated again |
| A scan finishes, or someone selects Re-scan | Evaluated again when the scan finishes |
| A vote is cast in Merge Pilot, or a risk is accepted | Evaluated again |
| The change approval changes in the tracker: approved, rejected, moved out of its approved status, deleted or moved to another key | The decision is recorded, then the merge request is evaluated (see Change approval) |
| A change policy is created, edited, deleted or reordered | Every 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 time | Picked 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 request | The 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:
| Situation | Check | Summary |
|---|---|---|
| Change management approved the pull request at the commit it was queued with | success, Change approved | Change management approved the pull request at the commit it was queued with. |
| The pull request is not known to Merge Pilot | failure, Change not approved | Merge Pilot does not know this pull request. |
| Its last decision is for another commit | failure | The pull request was queued with a commit change management has not decided on. |
| Its last decision is not Can merge | failure | Change 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:
| Flag | When | Audit action | Notification |
|---|---|---|---|
| Merged without approval | The 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_approval | Merged without approval |
| Merged in a change freeze | Merged during a freeze that holds merges (or an emergency-only freeze, for a change that is not an emergency) | mr_merged_in_freeze | Merged during a change freeze |
| Would have been held by a freeze | The same, for a watched merge request: nothing held it, so it is not non-compliant (would_have_held_in_freeze) | None | None |
| Approver merged | Someone who approved the change merged it, and the policy flags or forbids it | mr_sod_flag, mr_sod_block | Separation of duties broken, for a forbidden one |
| Would have been held | A watched merge request merged while its decision was not Can merge | mr_merged_would_have_blocked | None |
| Merged another way | Its 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 requests | mr_merged_through_other | None |
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}: thedecisionfield holds the latest decision:head_shaandtarget_branchit 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_violationrecord the merge flags.POST /api/v1/merge-requests/{id}/resyncruns the re-check for one merge request.
Audit log
| Action | When |
|---|---|
mr_policy_matched | A policy (or another version of it) now covers the merge request |
mr_gate_approved, mr_gate_pending, mr_gate_blocked | The gate was set to Can merge, Waiting or Blocked |
mr_watched_approved, mr_watched_pending, mr_watched_blocked | A watched merge request's decision changed (nothing was written) |
merge_group_checked | A GitHub merge queue group was answered |
mr_rejected | The policy closed the merge request |
mr_out_of_scope | The 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_block | A merge and its flags |
See also the Audit log.
Related pages
- Core concepts
- Controls
- Change management: putting a repository under change management.
- GitLab and GitHub: what the setup writes.
- Change calendar: change freezes.
- Merge requests and Change approval.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →