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
- 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.
- 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.
- Insights → Jobs. Search for the merge request's jobs: a job in Retry or Failed shows its last error (see Jobs).
- 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 card | Why | What to do |
|---|---|---|
| Looking up work items. | The work items of the latest commit are being read from the tracker | Wait; if it stays, check the Jobs page |
| The issue tracker could not be reached (…); retrying. | The tracker connection failed when reading the work items | Fix 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 run | Run 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 changes | Expected. 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 files | Split 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 role | Get 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 answer | Resync |
| Scanning the change for secrets. (and the other scans' pending lines) | A scan of the latest commit runs or waits in the queue | Wait. 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 control | Fix the work items, or have the risk accepted (below) |
| Creating the change approval. | The change approval is being opened in the tracker | Wait. 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 approvers | Approvers 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 card | Why | What to do |
|---|---|---|
| Merge requests matching policy "…" are not allowed. | The covering policy refuses its changes | Change 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 it | A 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 looks | Add 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 limit | Use 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 linked | Link 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 that | Resolve the request in the VCS |
| … Changes at <level> risk or above are held until someone accepts the risk. | The risk control holds the change | Someone 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 force | Wait 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 clean | See Troubleshooting scanning |
| N possible secret(s) found in the change. and the other findings | The scan found something the policy holds for | See Secret findings and Dependency scan |
| <KEY> was rejected. | The change approval was rejected | Rework 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 count | Give 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 brackets | Fix 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:
| Reason | What 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 tracker | Merge 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:
| Message | Why | What to do |
|---|---|---|
| link your account on this merge request's VCS in My profile before voting | Merge Pilot cannot tell whether you wrote the change | Link 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 change | Another approver decides it |
| you are not an approver for this change: you do not hold an approver role on the repository | You do not hold one of the policy's repository roles with your linked account | An 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 in | A 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 files | The policy asks for the code owners of the changed files | A code owner decides it (see Code owners) |
| you are not an approver for this change: you have no linked repository account with an approver role | Your linked account holds no approver role on this repository | Link the account that holds the role, or get the role |
| you committed to this change, and its policy does not let committers approve it | Separation of duties: you authored or committed a commit of the change | Another approver approves it. You may still reject |
| the change approval changed while you voted; reload and try again | New commits or a retarget replaced the change approval | Reload the page and vote on the current one |
| the change approval is already approved (or … already rejected) | It is decided | Nothing; 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 followed | Watched repositories are not gated | Nothing to vote on |
| standard changes are pre-approved; there is nothing to vote on | A standard change needs no approval | Nothing |
| this merge request has no change approval to vote on | The change approval does not exist yet | See 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
| Message | What to do |
|---|---|
| the merge request author cannot lift its risk block | Someone 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 block | Link your account first |
| the risk was already accepted, or a new commit changed the assessment; reload and review it | Reload the page |
Resync and Re-scan are refused
| Message | Why | What to do |
|---|---|---|
| only open merge requests, or ones whose change approval could not be moved, can be resynced | A merged or closed merge request is resynced only while it owes the tracker a move | Nothing to resync |
| resync failed: … | The VCS could not be read | Check the connection, then try again |
| moving the change approval failed: … | The move the tracker is owed failed again | Fix 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 merged | Nothing: they stay as they were |
| scans are off for watched repositories (Company → Repositories) | The company does not scan watched merge requests | Turn on scanning of watched merge requests on the company's Repositories tab (see Watching repositories) |
| scan already in progress | The scan is already waiting or running | Wait for it |
| the merge request's policy does not run the container image scan / … the infrastructure check | The control is Off in the merge request's policy | Nothing, or turn it on in the policy |
| the merge request's policy does not run the CI configuration check | The CI configuration check is Off in the merge request's policy | Nothing, 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).
Related pages
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →