CI Doctor
Find the first real CI failure—even when the job never reached a step—and propose the smallest evidence-backed fix.
What it inspects
- The run and job state, conclusion, annotations, timestamps, and matrix values.
- The first failing step when normal steps exist—or a separate pre-step path when they do not.
.github/workflows/*.ymland*.yamlat the failing commit.- Package manifests, lockfiles, test configuration, and recent diffs relevant to the error.
- Runner assignment and labels, environments, job conditions and dependencies, reusable workflows, permissions, and fail-fast or continue-on-error semantics.
- GitLab CI or CircleCI markers when those files or logs are supplied, with GitHub Actions as the primary workflow.
How it narrows the failure
CI Doctor selects one primary category: dependency error, test failure, configuration syntax, timeout, permission denied, missing secret, runner issue, or unresolved pre-step failure. It prefers the earliest concrete error and keeps matrix cancellations and later cascade failures separate.
The recommendation must connect the observed log line to the matching repository fact. A missing module is checked against the real manifest; a lockfile failure is checked against the repository's selected package manager; and a token failure is checked against the event and permissions before broader access is suggested.
When the job failed before any step ran
An empty steps array means normal step evidence is unavailable. It does not prove that application code failed, that a secret is missing, or even that a runner began executing the workflow.
CI Doctor checks the exact workflow revision, run and job state, annotations, runner labels and assignment, environment protections, job-level conditions and dependencies, reusable-workflow references, and matrix siblings. If none supports a narrower cause, it reports an unresolved pre-step failure and names the next read-only check instead of inventing a YAML change.
A representative pre-step diagnosis
What the report contains
- The run and job state, including whether normal step evidence exists.
- A one-sentence root cause—or an explicit unresolved pre-step failure—rather than generic possibilities.
- A short log excerpt plus file and line references when the evidence exposes them.
- One primary category and clearly labeled secondary symptoms.
- A copy-paste command, bounded YAML change, or patch summary.
- Confidence, unknowns, a local check where supported, and a precise CI rerun target.
- An optional pull-request path only after the owner confirms the mutation.
Access and safety boundaries
Diagnosis is read-only. For a live private repository, the agent needs GitHub CLI authentication with repository read access; otherwise, supply the workflow and redacted failed-step log. CI Doctor does not ask for secret values and cannot usually prove secret inventory from logs.
It asks before editing workflow or project files, rerunning a job, creating a branch, committing, pushing, or opening a pull request. Short log evidence should be redacted before it is shared outside the repository.
What it does not prove
The bundled failure patterns are a diagnostic aid, not an exhaustive CI engine. A plausible match is not enough when the workflow, manifest, lockfile, diff, or triggering event contradicts it. A green rerun confirms only the tested commit, event, matrix, runner, permissions, and dependency state.
Diagnose the run before changing the workflow
Use the buyer guide to record the failing run, locate the first concrete error, separate fork and secret boundaries, and verify one evidence-backed change.
Read the failed GitHub Actions diagnosis guide →Questions
What does CI Doctor inspect?
It inspects run and job state, annotations, workflow YAML at the failing commit, normal step logs when they exist, runner and environment context, matrix siblings, manifests, lockfiles, test configuration, and relevant diffs.
What does CI Doctor return?
It returns the run state, one evidence-backed root cause or an explicit unresolved pre-step failure, short evidence, the smallest fix or next read-only check, confidence and unknowns, and an approval boundary.
What if a GitHub Actions job failed with no steps or logs?
CI Doctor treats an empty steps array as missing execution evidence, not proof that application code or a secret failed. It switches to annotations, the workflow revision, runner labels, environment protections, job conditions, reusable workflows, and matrix siblings.
How does it handle fail-fast and continue-on-error?
It traces fail-fast matrix cancellations to the earliest required sibling failure and distinguishes job-level allowed failures from step-level continue-on-error behavior.
Does it need access to my GitHub repository?
For live private-repository runs, GitHub CLI must be authenticated with repository read access. You can instead provide workflow files and redacted logs. The skill does not require secret values.
Can CI Doctor see whether a repository secret exists?
Usually not from CI logs. It can show that a workflow references a secret and that the consuming step failed authentication, then distinguish likely causes such as a wrong name, environment approval, fork restrictions, expiration, or insufficient scope.
Will CI Doctor change files or open a pull request automatically?
No. Diagnosis starts read-only. It asks for confirmation before writing files, rerunning jobs, committing, pushing, or opening a pull request.
Does the diagnosis guarantee the next CI run will pass?
No. The failure catalog is a diagnostic aid, and repository-specific evidence controls the recommendation. The proposed fix still needs local checks where possible and a rerun under the relevant event, matrix, runner, and permission conditions.
Explain the failure before editing CI—even when no step ran.
Current price and purchase option are shown on Agensi. CI Doctor works with agents that read SKILL.md and keeps repository and GitHub changes behind confirmation.
Get CI Doctor on Agensi