Skip to main content
Video tutorial · 0:59

Troubleshooting merge requests

This page lists what holds a merge request up: the message the merge request page shows (the Policy card's line for each control, which is also the status comment and the gate's title in the VCS), why, and what to do. How a merge request goes through Merge Pilot is described in Merge requests and Merge gate.

Where to look first​

  1. The merge request page. The Policy card lists every control with its reason; the first enforced control that failed, or else the first still pending, is what holds the gate. The Timeline lists every event and job for the merge request.
  2. Resync in the page header. It reads CI and the change approval again from the VCS and the tracker, retries a change approval that could not be opened or moved, and evaluates the merge request again (see Resync). Most problems caused by a lost webhook or a tracker that was down end here.
  3. Insights → Jobs. Search for the merge request's jobs: a job in Retry or Failed shows its last error (see Jobs).
  4. The audit log, for what Merge Pilot decided and when (mr_gate_pending, mr_gate_blocked, change_approval_created, …).

The merge request is not in Merge Pilot​

Why: Merge Pilot never received, or ignored, the merge request's events. The usual causes:

  • the repository is neither watched nor under change management;
  • the target branch is not in the project's, or the company's, target branch patterns, or is one of the project's excluded branches;
  • the webhook does not reach Merge Pilot, or is refused (a wrong secret, an inactive connection, no valid license: every page then says No license is installed, so new merge requests are not being processed.).

What to do: check the provider's webhook delivery log for Merge Pilot's answer and follow Webhooks arrive but are ignored. Once the cause is fixed, the merge request is picked up at its next event (a push, an edit, a label), or when Merge Pilot next lists the repository's open merge requests (every List open merge requests every (hours), see Repositories settings). Merge requests open before a repository was added are listed when it is added. To have one processed at once: POST /api/v1/merge-requests/fetch with connection_id, repo_id and mr_number.

Merge requests open since a lost webhook are found by that listing. A listing that fails is tried again one interval later, and repositories of a connection that is turned off are not listed. A repository with 2,000 or more open merge requests is listed only up to that number and audited as open_mr_sweep_capped: the rest are found by their webhooks, or fetched by number.

A merge request deleted on the VCS is closed in Merge Pilot (closed reason deleted) and its undecided change approval cancelled; a watched one is checked the same way. One that comes back on the VCS is open again. When the repository itself no longer answers (deleted, moved, access lost), its page says so; see Removing a repository the VCS no longer answers for.

"Not processed yet" or "Not evaluated yet"​

Why: the event arrived, but the job that processes the merge request has not finished: it is waiting behind other work, retrying after an error, or it failed.

What to do: open Insights → Jobs and look for the merge request's mr_process job. A job in Retry shows its last error and the next attempt; a Failed one can be retried by a company admin once the cause is fixed (for example a revoked VCS token). Resync queues the merge request again.

The gate stays Waiting​

Waiting means no enforced control failed but at least one is still pending. The pending control's line says what it waits for:

Line on the Policy cardWhyWhat to do
Looking up work items.The work items of the latest commit are being read from the trackerWait; if it stays, check the Jobs page
The issue tracker could not be reached (…); retrying.The tracker connection failed when reading the work itemsFix the tracker connection (Test connection), then Resync
Waiting for CI to run on the latest commit. (or Waiting for <checks> to run on the latest commit.)No run of a trusted source has finished on the latest commit, or the named required checks have not runRun CI on the latest commit. Runs from sources the policy does not trust are listed as not counted (see CI). After a lost webhook, Resync reads the runs again
This change edits its CI configuration (…), so its CI runs prove nothing about it and do not count. …The change edits its own CI configuration, and the policy does not count runs of such changesExpected. Use a policy for CI changes that counts them (CI → count runs when the change edits CI configuration), or split the CI change out
The change is too large to read, so whether it edits its CI configuration is not known; its CI runs do not count.The VCS did not send the whole list of changed filesSplit the change, or use a policy that counts CI changes
N of M approving reviews on the latest commit.The Code review control needs more approving reviews in the VCS, on the latest commit, from people with a counted roleGet the reviews; reviews by people without a counted role are listed as Not counted
The reviews could not be read (…); they are read again when the merge request is next evaluated.The VCS did not answerResync
Scanning the change for secrets. (and the other scans' pending lines)A scan of the latest commit runs or waits in the queueWait. A scan waiting for a VCS rate limit is not failing (see Rate limits)
A change approval is opened once the work items check out and no risk hold applies; CI and scans can still run.The change approval waits for the enforced work items and the risk controlFix the work items, or have the risk accepted (below)
Creating the change approval.The change approval is being opened in the trackerWait. If it stays, look for the create_change_approval job on the Jobs page
Waiting for <KEY> to be approved. or Waiting for <KEY>: N of M approvals.The change approval waits for its approversApprovers vote in Merge Pilot or decide it in the tracker (see Approving and rejecting). When nobody is assigned, see Nobody is assigned the change approval

On GitHub, a pull request with a new commit has no Merge Pilot / change approval check until Merge Pilot decides on that commit, so GitHub waits too. On GitLab, Waiting and Blocked look the same: the bot user's approval is missing. When a decision could not be written to the VCS, a later evaluation or the periodic re-check writes it again.

The gate is Blocked​

Blocked means an enforced control failed. The gate's title (the check run's title on GitHub, the status comment on GitLab) names it:

Line on the Policy cardWhyWhat to do
Merge requests matching policy "…" are not allowed.The covering policy refuses its changesChange the merge request (its branch, paths, labels) or the policies. Which policy applies? on the Change policies page shows why this policy matched (see Trying policies out)
Merge requests matching policy "Not covered by a policy" are not allowed. Ask a Merge Pilot administrator to add a policy for this kind of change.A new VCS connection starts with only this catch-all, which refuses every merge request. Every merge request no other policy matches falls to itA policy manager adds policies for the connection, applies a template, or changes the catch-all (see The catch-all of a new connection). Open merge requests are evaluated again after a policy change
No work item is referenced in the commit messages, title or description.The Work items control is enforced and no key was found where the policy looksAdd a work item key, such as PAY-123, to the title, description, a commit message or the branch name, as the policy says (see Work items)
<KEY> is already used by N merge request(s) (limit M)The work item reached the policy's usage limitUse another work item, or a company admin selects Reset usage of <KEY> on the Issue tracker card
No issue tracker is configured for this project, so the change cannot be approved. (or … so work items cannot be checked.)The repository's VCS connection has no tracker linkedLink a tracker in the VCS connection's settings (see VCS connection settings), then Resync
Changes requested by …Someone requested changes in the VCS, and the policy holds on thatResolve the request in the VCS
… Changes at <level> risk or above are held until someone accepts the risk.The risk control holds the changeSomeone the policy allows selects Allow risk (see Accepting a risk)
Change freeze <name> until <time>: merges are held. (or : only emergency changes may merge.)A change freeze is in forceWait for it to end, or use an emergency change where the freeze lets those through (see Change freezes)
The secret scan failed: …, The dependency scan could not be completed: …A scan could not finish; a failed scan never counts as cleanSee Troubleshooting scanning
N possible secret(s) found in the change. and the other findingsThe scan found something the policy holds forSee Secret findings and Dependency scan
<KEY> was rejected.The change approval was rejectedRework the change: a new commit, or reopening the merge request, opens a new change approval. No more votes are taken on a rejected one
Only N people may approve this change, too few for any of the policy's approval groups (at least M approvals); add approvers, then resync.Fewer people may approve than the policy needs. The author, committers the policy keeps out, and people without a linked VCS account do not countGive more people the approver roles or add them to the approver pool, have approvers link their GitLab or GitHub account in My profile, then Resync
The change approval could not be created (…); it is retried automatically.The tracker refused or could not be reached; the reason is in the bracketsFix the cause (for example the tracker connection's project, issue type or required fields), then Resync to try at once

The change approval is not created​

The clearance track says Change approval not created when its creation failed; otherwise the Change approval line says what it waits for (above). A change approval is opened only when:

  • the repository is under change management (No change approval is opened while the repository is watched.);
  • a tracker is linked to the VCS connection;
  • the enforced work items check out and no risk hold applies;
  • enough people may approve it;
  • the change needs one: a standard change gets one only as a record (Open a change approval as a record), and an emergency change gets one for the review afterwards.

See When one is opened and When creation fails. The periodic re-check retries a failed creation after a pause that doubles with each failure, up to 6 hours; Resync retries at once.

The change approval does not move​

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.​

Why: a vote in Merge Pilot decided the change approval (or the merge request merged or closed), but moving it in the tracker failed, for example because the tracker's workflow offers no transition to the status. The vote stands; only the tracker is behind. The move is retried up to 5 times.

What to do: fix the tracker connection's statuses or Transition paths (see Jira → Statuses), then Resync, which also works on a merged or closed merge request. Or move it by hand in the tracker. See Tracker moves that fail.

A decision in the tracker is undone​

Why: Merge Pilot moved the change approval back and commented, because the decision does not count: the author decided their own change, the person may not decide this change, the tracker did not say who moved it, or only the assignee may decide and someone else did. Written as change_approval_vote_ineligible or change_approval_self_approval_blocked.

What to do: have an eligible approver decide it. A tracker decision counts only from someone Merge Pilot recognises: with the default Only from people who linked their VCS account, that person must have linked their account on the merge request's VCS (see Decisions made in the tracker and The same person in the tracker).

A decision in the tracker is not picked up​

Why: the tracker's webhook did not arrive. The periodic re-check reads the status of open and approved change approvals again (every 10 minutes by default).

What to do: Resync reads it at once. If decisions never arrive, check the tracker webhook (see Troubleshooting connections).

Nobody is assigned the change approval​

The Assignee shows No eligible approver: … with the reason:

ReasonWhat to do
nobody holding the approver roles on the repository may take it (its author, committers the policy keeps out and people without a linked account are left out)Give someone else the approver role, or have approvers link their GitLab or GitHub account in My profile
none of the N people who may take it was found in the trackerMerge Pilot cannot find these people in the tracker. Set their tracker account on the Users page, or adjust the company's matching rule (see People tab)

Anyone who may approve can still vote in Merge Pilot, assigned or not, or take it with Assign to me.

Votes are refused​

The Approve and Reject buttons answer with the reason:

MessageWhyWhat to do
link your account on this merge request's VCS in My profile before votingMerge Pilot cannot tell whether you wrote the changeLink your GitLab or GitHub account in My profile (see Linking an account)
authors cannot approve or reject their own change (the card says You wrote this change, so you cannot vote on it.)The author never decides their changeAnother approver decides it
you are not an approver for this change: you do not hold an approver role on the repositoryYou do not hold one of the policy's repository roles with your linked accountAn admin gives you the role in the VCS, or adds you to the approver pool
you are not an approver for this change: you are not in the approver pool "…"The policy asks for a pool you are not inA policy manager adds you to the approver pool
you are not an approver for this change: you are not a code owner of the changed filesThe policy asks for the code owners of the changed filesA code owner decides it (see Code owners)
you are not an approver for this change: you have no linked repository account with an approver roleYour linked account holds no approver role on this repositoryLink the account that holds the role, or get the role
you committed to this change, and its policy does not let committers approve itSeparation of duties: you authored or committed a commit of the changeAnother approver approves it. You may still reject
the change approval changed while you voted; reload and try againNew commits or a retarget replaced the change approvalReload the page and vote on the current one
the change approval is already approved (or … already rejected)It is decidedNothing; withdrawing an approval is done in the tracker (see Changing or withdrawing a vote)
this merge request's repository is watched: its change approval is no longer followedWatched repositories are not gatedNothing to vote on
standard changes are pre-approved; there is nothing to vote onA standard change needs no approvalNothing
this merge request has no change approval to vote onThe change approval does not exist yetSee The change approval is not created

Votes are cast as a person: a service API token is refused; use a session or a personal token.

Separation of duties cannot tell who committed​

The page says Commits by … match no person in Merge Pilot, so separation of duties cannot tell whether an approver wrote them. Link the account or add the e-mail to the person. The commit's author or committer is not recognised as a person of the company. Have them link their VCS account in My profile, or make sure the e-mail their commits carry is their Merge Pilot account's e-mail (see People tab). It is shown only where someone approves the change: a standard change that needs no approval (for example a dependency bot's) does not show it.

Code owners could not be read: …. Their approval cannot be given until they can.​

The CODEOWNERS file of the target branch could not be read. Until it can, the code owners requirement cannot be met. Fix the cause shown, then Resync.

Taking a change approval is refused​

Assign to me and Take over answer you cannot take this change approval: you … with the same reasons as votes (for example opened this change, committed to this change, and its policy does not let committers approve it), or:

  • link your account on this merge request's VCS in My profile first;
  • your tracker account is not known: ask an administrator to set it on the Users page: Merge Pilot needs your account in the tracker to assign it to you;
  • the change approval is approved: it is no longer taken (or another status): only an open change approval is taken.

Allow risk is refused​

MessageWhat to do
the merge request author cannot lift its risk blockSomeone else accepts the risk
only company administrators can lift this risk hold (the policy names no release pool)A company admin accepts it, or the policy names a release pool
link your account on this merge request's VCS in My profile before lifting a risk blockLink your account first
the risk was already accepted, or a new commit changed the assessment; reload and review itReload the page

Resync and Re-scan are refused​

MessageWhyWhat to do
only open merge requests, or ones whose change approval could not be moved, can be resyncedA merged or closed merge request is resynced only while it owes the tracker a moveNothing to resync
resync failed: …The VCS could not be readCheck the connection, then try again
moving the change approval failed: …The move the tracker is owed failed againFix the tracker connection's statuses or transition paths, or move it by hand
the merge request is merged: only open merge requests are scanned again; its recorded scans stay as they were (or closed)A merged or closed merge request's scans are the record of what mergedNothing: they stay as they were
scans are off for watched repositories (Company → Repositories)The company does not scan watched merge requestsTurn on scanning of watched merge requests on the company's Repositories tab (see Watching repositories)
scan already in progressThe scan is already waiting or runningWait for it
the merge request's policy does not run the container image scan / … the infrastructure checkThe control is Off in the merge request's policyNothing, or turn it on in the policy
the merge request's policy does not run the CI configuration checkThe CI configuration check is Off in the merge request's policyNothing, or turn the check on in the policy

Auditors see none of these buttons. See Re-running checks.

Change freezes​

The gate closed although the change is approved. A freeze that holds merges closes the gate of every change that is not let through, approved or not (Change freeze … until …: merges are held.). Approvals go on during the freeze.

The gate stays closed after the freeze ended. Held merge requests are evaluated again by the periodic re-check, so the gate opens at the first re-check after the end (every 10 minutes by default). Resync does it at once for one merge request.

A freeze has no effect. A Raise risk only freeze only raises the risk score, and nothing is scored while the company's risk assessment is off. Hold merges and Emergency changes only work either way. See Change freezes.

A merge during a freeze is flagged. Someone bypassed the gate during the freeze: the page says This change was merged during the change freeze "…", which held it. It is recorded as non-compliant. See What is flagged at merge.

Flagged "merged without approval"​

This change was merged in <GitLab or GitHub> before change management approved it. It is recorded in the audit log. Someone with the right to bypass the gate in the VCS merged it, or, on GitLab with Remove approvals when commits are added turned off, it merged on the bot's approval of an earlier commit before Merge Pilot had evaluated the new one. The flag stays; the change approval can still be decided afterwards. To prevent it, remove bypass rights in the VCS (the branch protection check reports them).

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

When a Merge Request Looks Stuck — ResyncYouTube ↗