Evidence-first diagnosis of failed GitHub Actions runs. Point it at a huge log (or a run ID) and get the most likely root cause, the exact log lines that prove it, and what to try next.
Real output from the local CLI (v0.1.0) on the public regression fixture test/fixtures/real-nextjs-jest-failure.log, a failed Next.js CI log. Recorded 2026-10-27 from a local checkout after npm run build. The command exits with code 0 because a diagnosis was produced; the CI run in the log is what failed.
Text transcript of the demo
$ node dist/cli.js analyze test/fixtures/real-nextjs-jest-failure.log
CIFirstAid - test/fixtures/real-nextjs-jest-failure.log
ROOT CAUSE [high confidence, test]
Jest: 2 tests failed
Evidence:
L26 ● server-reference-tree-shaking › tree shakes dependencies of an unused export containing an inline use-server function
L28 expect(received).toBe(expected) // Object.is equality
L30 Expected: false
L31 Received: true
L43 ● server-reference-tree-shaking › tree shakes dependencies of an unused export containing an inline use-cache function
L52 Tests: 2 failed, 2 passed, 4 total
Why: The test runner reported failing tests. The assertion details above are the concrete cause; the later "npm ERR!" / exit-code lines are only consequences.
Try:
1. Run just the failing test locally to reproduce, e.g. npx jest <file>.
2. If it passes locally, compare Node version, environment variables, timezone/locale and test ordering with the CI job.
3. Check whether the failure is timing-dependent (flaky) by re-running only the failed test.
Also found (lower priority; may be consequences of the above):
- [medium] Uncaught Error: Command failed with exit code 1 (EPERM): node run-tests.js --retries 0 --runs 3 test/e2e/app-dir/server-reference-tree-shaking/server-reference- (L64)
- [low] Missing environment variable: XDG_DATA_DIRS (L6)
- [low] A step failed with exit code 1 (L77)
Log: 82 lines | GitHub Actions format | timestamps removed | ANSI stripped | 1 error annotation(s)
$ echo $?
0
$ ci-first-aid analyze failed.log # abridged output from a real vercel/next.js failure
ROOT CAUSE [high confidence, test]
Jest: 2 tests failed
Evidence:
L2619 * server-reference-tree-shaking > tree shakes dependencies of an unused export...
L2621 expect(received).toBe(expected) // Object.is equality
L2623 Expected: false
L2624 Received: true
L2932 Tests: 2 failed, 2 passed, 4 total
Why: The test runner reported failing tests. The assertion details above are the concrete cause...
Try:
1. Run just the failing test locally to reproduce, e.g. npx jest <file>.
...
Also found (lower priority; may be consequences of the above):
- [low] A step failed with exit code 1 (L2957)
gh run view --log-failed is great, and CIFirstAid uses the same credentials. But it prints the log lines of failed steps; you still have to read them. Its own help text also warns that logs cannot always be associated with steps (UNKNOWN STEP) and that its per-job fallback is slow.
The real cause of a CI failure is usually not the last line. GitHub's final annotation is typically Process completed with exit code 1., and the actual error is hundreds of lines earlier. For example, in a real cli/cli run (kept as a test fixture) the last lines are:
GraphQL: Something went wrong while executing your query ...
##[error]Process completed with exit code 1.
CIFirstAid adds:
- Root-cause ranking. Specific signatures (
npm cilockfile drift,TS2307,Resource not accessible by integration...) outrank generic wrappers (exit code 1,ELIFECYCLE). Consequences are demoted. - Failure-window awareness. Output printed by earlier, successful steps (retried network blips, harmless warnings) is demoted; lines near runner-flagged
##[error]annotations are promoted. - Evidence with line numbers, secrets redacted.
- No-false-trail parsing. Script source echoed by the runner (
echo "Permission denied"),##[warning]lines andenv:dumps never count as evidence. - Offline analysis of any saved log; read-only API access for runs.
- Machine-readable output (
--json).
npm install -g @zuhairhalawa/ci-first-aid
# or run without installing
npx @zuhairhalawa/ci-first-aid analyze failed.logRequires Node.js 20 or newer. No runtime dependencies.
ci-first-aid analyze path/to/failed.log
ci-first-aid analyze path/to/failed.log --json
some-command | ci-first-aid analyze -Handles ordinary logs and GitHub Actions logs: ##[group]/##[error] markers, 7-digit timestamps, ANSI escape codes, BOMs, CRLF/LF/bare-CR line endings, Docker BuildKit #12 3.4 prefixes and UTF-16 files (e.g. produced by PowerShell > redirection). analyze never touches the network.
ci-first-aid run 1234567890 --repo owner/repo
ci-first-aid run https://github.com/owner/repo/actions/runs/1234567890
ci-first-aid run 1234567890 --repo owner/repo --attempt 2 --json| Option | Meaning |
|---|---|
-R, --repo [HOST/]OWNER/REPO |
Repository. Default: GH_REPO, else the origin git remote. |
--attempt N |
Re-run attempt to inspect (default: latest). |
--job ID |
Only diagnose one job. |
--max-jobs N |
Cap on failed jobs analyzed (default 10). |
--include-cancelled |
Also show cancelled jobs when other jobs failed. |
--hostname HOST |
GitHub Enterprise Server host (GH_HOST also works). |
--json, --no-color |
Output control. |
Authentication: for github.com, GH_TOKEN / GITHUB_TOKEN; for GitHub Enterprise hosts, GH_ENTERPRISE_TOKEN / GITHUB_ENTERPRISE_TOKEN. Otherwise the token from your existing gh auth login (via gh auth token). A github.com token is never sent to another host. The token needs read access to Actions (classic repo scope, or fine-grained Actions: Read).
What it calls (all GET): the run (/actions/runs/{id} or /attempts/{n}), its jobs (/actions/runs/{id}/attempts/{n}/jobs, paginated), each failed job's log (/actions/jobs/{id}/logs, which answers with a redirect to a signed storage URL that is followed without your token), and, only when a log is unavailable, check-run annotations. It never reruns, cancels, deletes or modifies anything; the client class has no non-GET code path and the test suite asserts it.
Handled situations: multiple failed jobs (analyzed concurrently, strongest cause summarized); re-run attempts; expired/deleted logs (falls back to annotations); 403/404/410 on logs; rate limits (reports the reset time); 401; transient 5xx (retried); network failures; runs still in progress; cancelled runs; runs that failed with no jobs at all (invalid workflow / startup failure; GitHub exposes no log for these, and the tool says so instead of guessing); very large logs (only the tail is kept past 64 MiB).
| Code | Meaning |
|---|---|
| 0 | A diagnosis was produced (including "nothing found"). |
| 1 | Runtime problem: unreadable file, network, authentication, API error. |
| 2 | Usage error. |
| Area | Examples |
|---|---|
| TypeScript | error TS2322, TS2307, config errors, grouped by file |
| npm / pnpm / yarn | npm ci lockfile drift, ERESOLVE, ETARGET, E404, E401/E403, EINTEGRITY, frozen-lockfile, engines mismatch, missing script, node-gyp builds |
| Node.js | module not found, ESM/CJS mismatch, OpenSSL 3 (ERR_OSSL_EVP_UNSUPPORTED), EADDRINUSE, ENOENT, unhandled rejections, uncaught errors with stacks |
| Tests | Jest, Vitest, Mocha, node:test/TAP failures with names and assertion details; "suite failed to run"; test timeouts; ESLint and Prettier |
| Python | tracebacks (deepest frame + exception), ModuleNotFoundError, pytest failures and collection errors, pip resolution/build failures |
| Missing tools / env | command not found, not recognized, spawn x ENOENT, missing environment variables, unbound variable |
| Permissions & auth | Resource not accessible by integration, OIDC id-token, git push denied, SSH, registry denied, 401/403, Permission denied, EACCES, dubious ownership |
| Actions configuration | unresolvable actions, invalid workflow expressions, missing required inputs, retired artifact actions, missing action.yml, artifact not found, missing checkout |
| Docker | failing RUN step (shows that step's last output), COPY source missing, Dockerfile problems, image pull failures, daemon unreachable, exec format error |
| Network | rate limits (GitHub API, Docker Hub, 429), DNS, TLS, resets/timeouts, connection refused to local services, upstream 5xx |
| Resources | job/step timeouts, cancellations (by user or concurrency), runner lost/shutdown, JS heap OOM, JVM/native OOM, Killed, disk full |
| Anything else | runner-flagged ##[error] lines with their surrounding output; then the last error-like lines, clearly marked low confidence |
--json prints one document. schemaVersion is bumped on breaking changes.
score is an internal 0-100 ranking value used to order findings; it is not a probability. Use confidence (high / medium / low) to judge how much to trust a finding.
For run, the document has run with jobs[] (each with failedSteps, logSource, notes and a diagnosis) and an overall primary.
- Detection is pattern-based. Confidence reflects how specific the evidence is;
lowmeans "best lead", not "cause". If a failure type is unknown, you get the runner-flagged lines and surrounding output, not an invented answer. - Evidence line numbers refer to the log as downloaded (including GitHub's setup lines).
- Oversized input is bounded, not rejected: for local files only the last 2,000,000 lines are analyzed (line numbers still refer to the original file, and the output says "input truncated"). Failures are normally at the end of a log.
- Logs are retained by GitHub for a limited time; expired logs fall back to annotations, which are much less detailed.
- Workflows that fail before any job starts have no log in the API.
- Redaction is best-effort pattern matching for common token formats on top of GitHub's own
***masking.
npm ci
npm run typecheck
npm test
npm run buildSee CONTRIBUTING.md for how to add a detector.
MIT
{ "schemaVersion": 1, "tool": { "name": "ci-first-aid", "version": "0.1.0" }, "mode": "analyze", // or "run" "source": "failed.log", "diagnosis": { "summary": "TypeScript compilation failed: 2 errors in 2 files", "primary": { "id": "typescript-compile-error", "category": "typescript", "kind": "root", "title": "...", "confidence": "high", "score": 100, "evidence": [{ "line": 12, "text": "src/a.ts(10,5): error TS2322: ..." }], "occurrences": 2, "explanation": "...", "suggestions": ["..."] }, "others": [], "stats": { "lines": 52, "ansiStripped": true, "timestamped": true, "githubFormat": true, "crlf": false, "errorAnnotations": 1, "truncated": false } } }