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
| Area | Covers |
|---|---|
| Sign-in | Wrong password, lockouts, directory (LDAP) and identity provider refusals, GitLab and GitHub sign-in, the account picker, linking accounts in My profile, sessions that end |
| Connections | Test connection failures, webhooks that do not arrive or are ignored, webhook secrets, the GitHub App (creation, installation, permissions), change management setup, rate limits |
| Merge requests | Merge 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 |
| Scanning | Secret and dependency scans that fail or cannot finish, files not scanned, project analyses that are stuck, refused or incomplete, SBOM export |
| Notifications | Nothing sent, failed deliveries, personal emails, email routes and the mail server, webhook signatures your endpoint rejects |
Where to look first
| Where | What it tells you | Who sees it |
|---|---|---|
| The merge request page | The 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 log | Who 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 → Jobs | The 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 deliveries | Each 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 request | Not 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.