Diagnose a Depot CI failure
depot_diagnose_ci_failureDiagnose why a CI run, workflow, job, or attempt failed and get clustered root causes, AI-written explanations, suggested fixes, and evidence log lines.
Instructions
Explain why a Depot CI run, workflow, job, or attempt failed.
Reach for this first whenever someone asks why CI failed, what broke the build, or to fix a failing job. It calls Depot's server-side failure analysis, which clusters every failure in the target by root cause and returns, for each cluster: the error message, an AI-written diagnosis, a suggested fix, and the exact log lines that are the evidence.
Prefer this over depot_get_ci_logs. Depot bounds this response server-side, so it costs far less context than raw logs, and it already works out which job is the real root cause rather than a downstream casualty. Use depot_get_ci_logs afterwards only if you need more detail on a specific attempt.
Pass whichever identifier you have in "id" — a run, workflow, job, or attempt ID. This server works out which kind it is; set "targetType" only when you already know it and want to skip that step.
How to read the returned "state":
"focused_failure": one clear culprit. Read representativeAttempts.
"grouped_failures": several distinct root causes, clustered by fingerprint. Read failureGroups.
"over_limit": too many failures to analyse at this level. narrowerTargets gives the IDs to call this tool again with.
"empty": Depot found no failure evidence. The target may still be running, may have succeeded, or may be old enough that its logs have aged out.
Diagnoses and suggested fixes are generated by Depot's AI and can be wrong — treat them as a lead to verify, not a fact. Read-only: this never retries, cancels, or triggers anything.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A Depot CI identifier: a run, workflow, job, or attempt ID. Pass whatever you have — the server resolves which kind it is. | |
| targetType | No | What kind of thing "id" refers to. Omit unless you know it; the server otherwise infers it, falling back to trying each kind in turn. | |
| maxEvidenceLines | No | Cap on evidence log lines per failing attempt. Set 0 to get diagnoses and fixes without any log lines. | |
| maxFailureGroups | No | Cap on how many clustered root causes to return. Raise only if 5 was not enough. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | One of focused_failure, grouped_failures, over_limit, empty, or unknown. | |
| target | Yes | ||
| context | Yes | ||
| nextSteps | Yes | Depot's suggested follow-ups, rewritten as calls to this server's tools. | |
| truncation | Yes | ||
| emptyReason | No | ||
| aiDisclosure | No | ||
| failureGroups | Yes | ||
| contentWarning | Yes | Reminder that names, log lines, and diagnoses here are unverified CI output. | |
| narrowerTargets | Yes | Present when state is over_limit: narrower ids to re-run this tool against. | |
| resolvedTargetType | Yes | The target kind that Depot accepted for this id. | |
| representativeAttempts | Yes |