Skip to main content

Troubleshooting

When something does not work as expected, Merge Pilot usually already says why: in a line on the merge request page, a job's last error, an audit entry or a delivery's last answer. These pages list the messages people see, by area, with why each appears and what to do.

By area​

AreaCovers
Sign-inWrong password, lockouts, directory (LDAP) and identity provider refusals, GitLab and GitHub sign-in, the account picker, linking accounts in My profile, sessions that end
ConnectionsTest connection failures, webhooks that do not arrive or are ignored, webhook secrets, the GitHub App (creation, installation, permissions), change management setup, rate limits
Merge requestsMerge requests not processed, a gate that stays Waiting or Blocked, change approvals not created or not moving, refused votes and take-overs, separation of duties, Resync and Re-scan refusals, change freezes
ScanningSecret and dependency scans that fail or cannot finish, files not scanned, project analyses that are stuck, refused or incomplete, SBOM export
NotificationsNothing sent, failed deliveries, personal emails, email routes and the mail server, webhook signatures your endpoint rejects

Where to look first​

WhereWhat it tells youWho sees it
The merge request pageThe decision of each control with its reason, the change approval, the scans, and a timeline of everything done with the merge request (see Merge requests)Everyone in the company
Administration → Audit logWho did what and when, including what Merge Pilot did by itself, refused sign-ins with their reason, accepted webhooks (webhook_accepted) and failed jobs (job_failed). Filter by Status → Failure to see what went wrong (see Audit log)Platform admins, company admins, auditors
Insights → JobsThe background work: what waits, runs, retries or failed, with the last error and the next attempt. Company admins retry a failed job once its cause is fixed (see Jobs)Everyone in the company; retrying: company admins, platform admins
Delivery log on the Notifications tab, and each route's Recent deliveriesEach Slack, Teams, email, webhook or personal email delivery with its attempts and the last answer or error, and Send again (see Delivery log and failures)Company admins, platform admins
Resync on a merge requestNot a log but a fix: reads CI and the change approval again from the VCS and the tracker, retries what failed, and evaluates the merge request again (see Resync)Everyone in the company except auditors

Two more places help with connections:

  • The provider's own webhook delivery log (GitLab, GitHub, Jira) shows what Merge Pilot answered to each delivery (see Troubleshooting connections).
  • The Projects page shows Background work while something is left to do: imports, re-evaluations after a policy change, webhook updates, work waiting for a VCS rate limit (see Repositories).

Things that fix themselves​

Merge Pilot recovers from most outages without anyone acting:

  • Failed jobs are retried, by default up to 3 attempts with a growing wait; a VCS rate limit makes a job wait without using an attempt.
  • The periodic re-check (every 10 minutes by default) goes over open merge requests that are still waiting: it reads CI runs and tracker decisions whose webhook was lost, retries change approvals that could not be opened and tracker moves that failed, and opens or closes the gate when a change freeze starts or ends (see The periodic re-check).
  • Notification deliveries are retried up to 5 times.

So after an outage of the VCS or the tracker, wait for the next re-check, or select Resync on the merge requests that matter now. What Merge Pilot does in each outage is described in The VCS or the tracker is unavailable.