CI Doctor
Find the first real CI error, explain it with repository evidence, and propose the smallest credible fix.
What it inspects
- The run, job, and first failing step from GitHub Actions logs.
.github/workflows/*.ymland*.yamlat the failing commit.- Package manifests, lockfiles, test configuration, and recent diffs relevant to the error.
- Runtime, package-manager, cache, matrix, permission, environment, and working-directory context.
- 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, or runner issue. It prefers the earliest concrete tool error over the final exit-code summary and keeps 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.
A representative diagnosis
What the report contains
- A one-sentence root cause rather than a list of 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.
- A local check where the repository supports one 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 reads the failed run and step logs, workflow YAML, relevant package manifests and lockfiles, test configuration, and recent diffs. It begins with GitHub Actions and can recognize GitLab CI or CircleCI markers from supplied files and logs.
What does CI Doctor return?
It returns one primary failure category, a one-sentence root cause, short supporting evidence, a copy-paste fix or patch summary, and a clear verification step. Secondary symptoms remain separate.
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 first failure before editing CI.
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