Skip to main content

Block a merge until the Jira change approval is approved

· 11 min read
The team behind Merge Pilot

A change approval in Jira only matters if the merge waits for it. When the approval lives in one system and the merge button in another, a merge request can merge while its ticket is still open, or merge a commit nobody approved. This guide explains how Merge Pilot ties the two together on GitLab and GitHub, and what happens on the detours: new commits, a new target branch, a rejection and an emergency.

The problem: two systems, one decision​

Many teams already open a change ticket for each release. The ticket is reviewed and approved in Jira, while the code is reviewed and merged in GitLab or GitHub. Nothing connects the two decisions:

  • the merge request can merge before the ticket is approved;
  • the ticket can be approved for code that changed afterwards;
  • a merge request can be moved to another target branch after its ticket was approved for the first one.

Merge Pilot closes those gaps by making the change approval part of the merge decision. A change policy decides whether a merge request needs a change approval at all, which checks must pass and who must approve. The result is written into the VCS as the merge gate, so GitLab or GitHub itself refuses the merge until the policy is met for the merge request's latest commit.

How the merge gate works on each VCS​

The gate is set again after each evaluation, and it is always for one commit and one target branch. It takes one of three states: Can merge, Waiting or Blocked. See Merge gate for the full rules.

On GitLab​

On GitLab the gate is an approval rule named Merge Pilot — <branch> on each protected target branch, whose only approver is the connection's bot user. When the policy is met, the bot approves the merge request for the commit the decision is for. When the decision is Waiting or Blocked, the bot withdraws its approval. Nobody else can meet that rule.

The setup step Remove approvals when commits are added (on by default) makes GitLab remove the bot's approval as soon as a commit is pushed. Approval rules need GitLab Premium or Ultimate; the setup reports that when GitLab refuses the rule. See GitLab change management setup steps.

On GitHub​

On GitHub the gate is the check Merge Pilot / change approval, reported by the connection's GitHub App on each pull request's head commit. A ruleset named Merge Pilot change management requires that check on the target branches, accepted from the App only. Success means Can merge, in progress means Waiting, failure means Blocked.

A new push has no check yet, so GitHub holds the new commit until Merge Pilot decides on it. See What Merge Pilot writes to each repository.

The same decision on both​

GitLabGitHub
What holds the mergeApproval rule met only by the bot userRequired check from the GitHub App only
Can mergeBot approves for that commitCheck run concludes success
WaitingBot approval missingCheck run in progress
BlockedBot approval missingCheck run concludes failure
New commitApproval removed on push (by default)No check on the new commit yet

On both, Merge Pilot keeps one status comment on the merge request with the policy, one line per control and the commit the decision is for.

Setting it up​

The order below assumes a Jira connection and a GitLab or GitHub connection already exist.

  1. Link the tracker. In the VCS connection's settings, choose the Jira connection as the Linked tracker connection. Without a linked tracker only standard changes can merge. See VCS connection settings.
  2. Set up the Jira side. In the Jira connection's tracker settings, choose the Project and Issue type change approvals are opened as, the Closing statuses (approve), the Rejection statuses and, if a policy will ask for more than one approval, the Reopen status. See Tracker settings and How a change approval moves through Jira.
  3. Write a normal-change policy. Under Governance → Change policies, add a policy with the change type Normal change, its conditions on the Scope tab (for example the target branches main, release/*), and its approvers under Who must approve. The policy templates are a quick start.
  4. Try it. Use Which policy applies? to check which policy covers a described change, and Test run to try unsaved edits on a real merge request. See Trying policies out.
  5. Put the repositories under change management. The setup shows each step it will write to the repository, required and optional, and asks for consent before writing anything. See Setup steps and consent.

From then on, every merge request into a covered branch is matched to a policy and gated.

When the change approval is opened​

For a normal change, the change approval is opened in Jira once the enforced work items check out and no risk hold applies, and once enough people may approve it. CI and scans do not have to finish first; they run while approvers look at the change. See When one is opened.

The issue carries a summary and description from the tracker settings' templates (or a default record with the repository, branches, author and work items). It is assigned as the policy's Assign the change approval says (a random approver by default, never the author), and Merge Pilot comments on the merge request with the key and the next steps.

Approving it​

An approval counts whether it is made in Jira or in Merge Pilot:

  • Moving the issue to a closing status in Jira is an approval by whoever moved it.
  • Approve on the merge request's Approval card in Merge Pilot counts the same way, and Merge Pilot moves the issue in Jira once the change approval is decided.
  • When the policy asks for more than one approval, each partial approval in Jira sends the issue back to the reopen status for the next approver.

Every decision is checked before it counts. The author's own approval is ignored and the issue goes back. A decision by someone who may not decide the change is ignored too. See Decisions made in the tracker.

Once the policy's approvals are met, the Change approval line passes and, if every other enforced control has passed, the gate opens.

Rejecting it​

One rejection is enough. Moving the issue to a rejection status, or Reject in Merge Pilot (with a reason of at least five characters), blocks the gate. The policy's Missing work items or a rejected change approval then decides the next step: Block until fixed (the default) keeps the merge request open and blocked; Close the merge request closes it. To go on after a rejection, push new commits or reopen the merge request; a new change approval is opened.

What new commits do​

Every decision is for the latest commit, so a push always reopens the question. The gate waits again until the controls have passed for the new commit. What happens to the change approval is the policy's New commits after a change approval (Lifecycle tab):

SettingThe change approvalApprovals
Open a new change approval (default)Superseded, commented as such, and replaced by a new one for the new commit, linked to the old one in JiraApproved from scratch
Reopen the change approvalThe same issue moves back to the reopen status and now covers the new commitVotes cleared
Keep the approvalThe issue now covers the new commit; each time is written to the audit logKept

Whatever the setting, an approval made in Jira for older code does not count for the new commit, and decisions on a superseded change approval are ignored. See New commits.

Keep the approval is a deliberate trade-off: it saves a second round of approvals for fixes pushed after approval, at the cost of an approval that no longer covers exactly what merges. If you use it, use it for policies where that is acceptable, and expect the audit log to show each time it applied.

What retargeting does​

An approval into one branch is not an approval into another. When a merge request is moved to another target branch:

  • A branch change management covers: the merge request is processed again under the policy for the new branch, its change approval is retired with the reason (its target branch changed), and a new one is opened when the new policy needs one. The gate waits again.
  • A branch it does not cover: the merge request leaves change management, and an undecided change approval is cancelled and moved to the tracker's cancelled status.
  • Moved back to a covered branch: it is gated again from the start, with a new change approval.

See The target branch is changed.

Emergency changes​

Some changes cannot wait for a change approval. An Emergency change policy, usually matched by a label such as emergency, lets a change merge as soon as its other enforced controls pass. The change approval is opened for a review afterwards, due within the policy's Review deadline (72 hours unless the policy sets another).

  • Whoever added the label declares the emergency. The declaration is recorded on the merge request, written to the audit log and announced.
  • The company, or the emergency policy itself, can limit who may declare one: only an approver pool, never the author, or a number of emergencies per repository in a window. When the rules are not met, the emergency policy does not match and the next policy covers the change as usual.
  • The review takes the same checks as any change approval: the author never decides it and only the policy's approvers count.
  • A review not decided by its deadline is reported once, as Emergency review overdue.

See An emergency is declared and Who may declare an emergency.

What if someone merges anyway​

An administrator on the VCS can bypass the gate. Merging cannot be stopped from outside the VCS, so Merge Pilot records what merged against its last decision for that commit and branch. A merge the gate had not opened is flagged as Merged without approval, written to the audit log and announced, and the Jira issue gets a warning comment. Approvals withdrawn in Jira after the merge are flagged as well. See What is flagged at merge.

Merge Pilot also checks gated repositories regularly for loosened protection, such as an unprotected branch, an edited approval rule or a ruleset bypass, and reports new gaps. See Branch protection check.

Lost webhooks and outages​

If a Jira or VCS webhook is lost, the periodic re-check reads the change approval's latest status and the CI runs again, and applies what it finds. When Jira cannot be reached while a change approval is being opened, the gate stays blocked and creation is retried; Resync on the merge request tries at once. An emergency change is not held by a tracker outage; its review change approval is opened once Jira is back.

Next steps​

The Merge gate feature page sums up the gate on both VCSs, and the Change approval lifecycle page follows a change approval from opening to merge. To see the gate on your own GitLab or GitHub with your Jira workflow, ask for a demo.