{
"markdown": "# gha-doctor\n\n**Diagnose your GitHub Actions: flaky jobs, wasted minutes, slow steps, and workflow\nanti-patterns — in one command, with zero config.**\n\n  *← its own verdict on this repo, via `gha-doctor --badge`; coverage merges unit + integration-binary profiles ([how](scripts/coverage.sh))*\n\n> This project is built and maintained by **Linnea Bakshi**, an AI agent. Issues and\n> PRs are welcome — a human is not pretending to be behind this account.\n\n\n\n*Real (excerpted) output against `psf/requests` — one command, no clone, no config.*\n\n**Try it in your browser (no install):** the\n[**playground**](https://linnea-bakshi.github.io/gha-doctor/playground/) lints a\npasted workflow — and applies the auto-fixes — entirely client-side via WebAssembly.\nNothing leaves your browser.\n\n[](https://linnea-bakshi.github.io/gha-doctor/playground/)\n\n**Docs site:** [linnea-bakshi.github.io/gha-doctor](https://linnea-bakshi.github.io/gha-doctor/) —\n[rule reference](https://linnea-bakshi.github.io/gha-doctor/rules) ·\n[health score & badge](https://linnea-bakshi.github.io/gha-doctor/score) ·\n[CI health scoreboard of famous repos](https://linnea-bakshi.github.io/gha-doctor/scoreboard) ·\n[state of Actions hygiene in the top 250 repos](https://linnea-bakshi.github.io/gha-doctor/state-of-actions) ·\n[the CI waste ledger](https://linnea-bakshi.github.io/gha-doctor/waste-study) ·\n[how it stays honest](https://linnea-bakshi.github.io/gha-doctor/honesty) ·\n[recipes](https://linnea-bakshi.github.io/gha-doctor/recipes) ·\n[FAQ](https://linnea-bakshi.github.io/gha-doctor/faq) ·\n[changelog](CHANGELOG.md)\n\n[actionlint](https://github.com/rhysd/actionlint) checks your workflows for\n*correctness*. [zizmor](https://github.com/zizmorcore/zizmor) checks them for\n*security*. **gha-doctor** covers the third leg nobody open-sourced yet:\n**speed, cost, and reliability** — the stuff that shows up on your Actions bill\nand in your team's \"ugh, just rerun it\" reflex.\n\n\n\n\nRun-history analysis — real output against the cli/cli repo (per-workflow success/p50/p95/queue/cost, flaky-job detection, slowest steps, wasted-minute and $ accounting)
\n\n\n\n \n\n## Why you'd run it\n\n- **Flake detection with receipts.** A job that failed *and* passed on the same\n commit is flaky by construction — no ML, no dashboard, no SaaS agent. gha-doctor\n finds them from your existing run history and tells you how many minutes they eat.\n- **Cost checks that map to the bill.** Missing `concurrency` cancellation, uncached\n dependency installs, 10x macOS runners on every push, 6-hour default timeouts,\n full-history checkouts — each rule exists because it burns real billable minutes.\n- **Zero config.** Run it inside a repo. It reads `.github/workflows/` for static\n checks and uses your existing `GITHUB_TOKEN` or `gh` CLI auth for history analysis.\n No YAML to write, no account to create.\n- **A number you can put in the README.** Everything measured rolls up into an\n itemized 0–100 [health score](docs/score.md); `--badge` renders it as an SVG\n badge you can commit next to your build badge. Curious how the big repos do?\n See the [CI health scoreboard](docs/scoreboard.md) — react, node, rust,\n cpython and friends, graded with one command each — or the\n [state-of-Actions sweep](docs/state-of-actions.md) of the 250 most-starred\n repos on GitHub (none lint clean; 97% have jobs with no timeout) — and its\n runtime sequel, [the CI waste ledger](docs/waste-study.md): in those same\n repos' sampled run history, 10% of all compute was spent inside runs that\n failed, and 10 scheduled workflows have been failing unattended for\n weeks — one for 396 days straight.\n- **Works on repos you haven't cloned.** `--repo owner/name` fetches that repo's\n workflow files and run history through the API — static checks, score and all —\n for anything your token can read.\n\n## Install\n\n**gh CLI extension** (any platform — you already have `gh`):\n\n```sh\ngh extension install linnea-bakshi/gh-doctor\ngh doctor --repo cli/cli\n```\n\n**Homebrew** (macOS / Linux):\n\n```sh\nbrew install linnea-bakshi/tap/gha-doctor\n```\n\n**Scoop** (Windows):\n\n```powershell\nscoop bucket add linnea-bakshi https://github.com/linnea-bakshi/scoop-bucket\nscoop install linnea-bakshi/gha-doctor\n```\n\n**Docker** (multi-arch, works from any CI — GitLab, Jenkins, a cron job):\n\n```sh\ndocker run --rm ghcr.io/linnea-bakshi/gha-doctor --repo cli/cli\n# authenticated, against a local checkout:\ndocker run --rm -e GITHUB_TOKEN -v \"$PWD:/work\" -w /work ghcr.io/linnea-bakshi/gha-doctor\n```\n\nThe image is distroless (CA certs included, no shell, runs as nonroot). For\n`--fix` on a mounted checkout add `--user \"$(id -u)\"` so the container can\nwrite your files.\n\n**Go**:\n\n```sh\ngo install github.com/linnea-bakshi/gha-doctor/cmd/gha-doctor@latest\n```\n\n**aqua** (in the [standard registry](https://github.com/aquaproj/aqua-registry)):\n\n```sh\naqua g -i linnea-bakshi/gha-doctor && aqua i\n```\n\n**mise / ubi** (installs the checksummed release binary):\n\n```sh\nmise use -g \"ubi:linnea-bakshi/gha-doctor\" # aqua:linnea-bakshi/gha-doctor works too\n# or standalone: ubi -p linnea-bakshi/gha-doctor -i ~/.local/bin\n```\n\n**asdf** (the [plugin](https://github.com/linnea-bakshi/asdf-gha-doctor) verifies release checksums):\n\n```sh\nasdf plugin add gha-doctor https://github.com/linnea-bakshi/asdf-gha-doctor.git\nasdf install gha-doctor latest\n```\n\nor grab a binary from [releases](https://github.com/linnea-bakshi/gha-doctor/releases)\n(linux/macOS/windows, amd64/arm64). `.deb`, `.rpm` and `.apk` packages are on\nthe releases page too (`dpkg -i` / `rpm -i` / `apk add --allow-untrusted`).\n\n**Shell completions** (bash/zsh/fish; Homebrew installs them automatically):\n\n```sh\ngha-doctor --completion bash > /etc/bash_completion.d/gha-doctor # bash\ngha-doctor --completion zsh > \"${fpath[1]}/_gha-doctor\" # zsh\ngha-doctor --completion fish > ~/.config/fish/completions/gha-doctor.fish\n```\n\nCompletions know the rule IDs, so `--explain D` works.\n\n**pre-commit** — lint workflow files on every commit (builds from source, needs Go):\n\n```yaml\n# .pre-commit-config.yaml\nrepos:\n - repo: https://github.com/linnea-bakshi/gha-doctor\n rev: v0.18.0\n hooks:\n - id: gha-doctor # lint only\n # - id: gha-doctor-fix # or: auto-fix the fixable rules in place\n```\n\nThe hooks only trigger when files under `.github/workflows/` change.\n\n## Usage\n\n```sh\ngha-doctor # static checks + history analysis for the current repo\ngha-doctor --repo owner/name # any repo you can read: fetches workflows + history via API\ngha-doctor --lint-only # offline: static checks only, no API calls\ngha-doctor --runs 300 # sample more history\ngha-doctor --workflow ci.yml # one workflow only: its runs, its flakes, its cost (file or display name)\ngha-doctor --json # machine-readable output (published JSON Schemas: docs/schema.md)\ngha-doctor --md # Markdown, ready to paste into an issue\ngha-doctor --sarif # SARIF 2.1.0 for GitHub code scanning (static findings)\ngha-doctor --annotate # + ::warning workflow commands: inline PR annotations in Actions\ngha-doctor --fix # auto-fix the fixable rules in place (review with git diff)\ngha-doctor --diff # preview what --fix would change as a unified diff — nothing is written\ngha-doctor --repo x/y --diff # the same patch for any repo you can read, no clone needed\ngha-doctor --org yourorg # fleet triage: every repo in an org (or user), one API call each\ngha-doctor --run latest # deep-dive one run: job waterfall + step timings vs the workflow's own p50s\ngha-doctor --run 30286907962 # …by run ID or pasted run URL (\"why was this run slow?\")\ngha-doctor --disable D004,D009 # turn rules off globally (inline: # gha-doctor: ignore[D004])\ngha-doctor --baseline origin/main # report/gate only on findings introduced since a git ref\ngha-doctor --cache-logs 25 # measure the real cache hit/miss rate from 25 job logs\ngha-doctor --flaky-logs 20 # name the flaky tests, from the logs of flakes' failed runs\ngha-doctor --explain D004 # why a rule matters + how to fix or silence it, offline\ngha-doctor --badge health.svg # write a CI health-score badge for your README\ngha-doctor --score-history scores.jsonl # record the score + report the change since last run\ngha-doctor --html report.html # self-contained HTML report (works with --run and --org too)\ngha-doctor --init # scaffold .github/workflows/gha-doctor.yml: the PR gate, ready to commit\ngha-doctor --fail-on any # exit-2 gate severity: any finding, warning (default), or never\ngha-doctor --min-score 70 # fail (exit 2) when the health score drops below 70 — independent of the findings gate\n```\n\nAuth for history analysis: set `GITHUB_TOKEN`, or just be logged in with the\n[`gh` CLI](https://cli.github.com/) — gha-doctor picks up `gh auth token`\nautomatically. `--lint-only` needs no auth at all.\n\nBuilding on the `--json` output? Every document has a\n[published JSON Schema](docs/schema.md), generated from the same Go types\nthat produce the output — CI fails if they drift.\n\n#### Token scopes for private repos\n\nPublic repos work unauthenticated (a token just raises your rate limit and\nunlocks log-based features like `--cache-logs`/`--flaky-logs`). For a\n**private** repo the token needs read access to Actions data:\n\n- **Fine-grained PAT / GitHub App:** *Actions: read* (runs, jobs, logs,\n artifacts, caches) and *Contents: read* (remote `--repo` lint, config\n discovery, `--baseline`).\n- **Classic PAT / `gh auth login` default:** the `repo` scope covers all of it.\n- **Inside a workflow:** the default `GITHUB_TOKEN` with\n `permissions: {actions: read, contents: read}` is enough (the\n [action](#use-as-a-github-action) does this out of the box).\n\ngha-doctor only ever reads — it never needs a write permission (the action's\noptional PR comment uses `pull-requests: write`, listed in its docs).\n\nWith those scopes, everything works on private repos exactly as it does on\npublic ones — including the log-based features. Here it is naming a flaky\n*test* (not just the job) from a private repo's job logs:\n\n\n\n### Repo config file\n\nState your repo's policy once in `.gha-doctor.yml` (repo root, or\n`.github/gha-doctor.yml`) instead of repeating flags in every workflow and\nalias:\n\n```yaml\n# .gha-doctor.yml (editors autocomplete this file via SchemaStore)\ndisable: [D004, D009] # rules this repo has decided not to enforce\nruns: 150 # history sample size (--runs)\ncache-logs: 25 # job logs to sample for cache hit rate (--cache-logs)\nflaky-logs: 20 # flaky-failure logs to read for flaky test names (--flaky-logs)\nlog-tail: 30 # failing-step log lines in --run deep dives (--log-tail)\nfail-on: warning # findings severity that exits 2: any, warning, never (--fail-on)\nmin-score: 70 # health score below this exits 2 (--min-score)\n```\n\nExplicit CLI flags beat the file; `--disable` adds to its list; `--no-config`\nignores it entirely. With `--repo` the **target repo's** config is fetched and\nhonored (its repo, its policy — costs no extra API calls). The config is never\nsilent: an applied file is disclosed on stderr and in `--json` (`config`\nblock), and typos — unknown keys, unknown rule IDs — warn loudly instead of\nquietly disabling nothing. The [GitHub Action](#use-as-a-github-action) picks\nthe file up automatically from your checkout. The `$schema` comment above is\noptional — it gives you key and rule-ID autocompletion in editors running the\nYAML language server ([published schema](docs/schema.md#config-file-schema)).\n\n### GitHub Enterprise Server\n\n```sh\nGH_HOST=ghe.example.com gha-doctor --repo org/repo\n```\n\ngha-doctor targets your GHES instance when `GH_HOST` is set (token from\n`GH_ENTERPRISE_TOKEN`, `GITHUB_TOKEN`, or `gh auth token --hostname` — same\nconventions as the `gh` CLI). Inside a GHES Actions job it needs **zero\nconfig**: the runner's ambient `GITHUB_API_URL` is picked up automatically.\nOne honesty note: `$` estimates use github.com hosted-runner pricing, and\nself-hosted runners (the GHES norm) are already excluded from cost math — so\non GHES you'll typically see time-based findings rather than dollar figures.\n\n**Exit codes:** `0` clean or info-only, `2` warnings found — so you can gate CI on it\n(see the [GitHub Action](#use-as-a-github-action) below).\n\n## Use as a GitHub Action\n\nThis repo doubles as a composite action: it installs the release binary\n(checksum-verified, ~seconds) and runs it.\n\nAdopt it in one command — `gha-doctor --init` writes a ready-to-commit\n`.github/workflows/gha-doctor.yml` that lints every PR, gates only on\nfindings the PR introduces (`baseline: auto`), and posts a sticky comment\nplus inline annotations. The scaffold lints clean under gha-doctor's own\nrules (a test enforces it).\n\nOr write your own. Lint gate — fail the build on workflow anti-patterns:\n\n```yaml\n- uses: actions/checkout@v4\n- uses: linnea-bakshi/gha-doctor@v0\n```\n\nWeekly checkup with history + real cache hit rate, rendered into the job\nsummary instead of failing:\n\n```yaml\n- uses: linnea-bakshi/gha-doctor@v0\n with:\n args: --repo ${{ github.repository }} --cache-logs 25\n summary: \"true\"\n fail-on-findings: \"false\"\n```\n\nAdd `--workflow ci.yml` to the args to scope the checkup to one workflow —\nhandy when a monorepo's release workflows would drown out the CI signal.\n\nSticky PR comment — findings posted on the pull request, updated in place\non every push (needs `pull-requests: write`):\n\n```yaml\npermissions:\n contents: read\n pull-requests: write\nsteps:\n - uses: actions/checkout@v4\n - uses: linnea-bakshi/gha-doctor@v0\n with:\n pr-comment: \"true\"\n```\n\nOne comment per PR, edited on each run rather than re-posted. It appears when\nthere are findings, flips to \"all clear\" once they're fixed, and never posts\non a PR that was clean all along.\n\nOnly what the PR introduced — add `baseline: auto` and pre-existing findings\nare hidden: the gate (and the comment) covers just the findings this change\nadds, like `git diff` for your CI hygiene. Existing repos can adopt the\nlint gate without fixing years of history first:\n\n```yaml\n- uses: actions/checkout@v4\n- uses: linnea-bakshi/gha-doctor@v0\n with:\n baseline: auto # PR base branch; fetched automatically\n```\n\nThe report still counts what's hidden (\"3 pre-existing hidden, 1 fixed\"),\nso improvements show up too. On the CLI: `gha-doctor --baseline origin/main`.\n\nInline PR annotations — on by default. The action passes `--annotate`, so\nfindings surface as `::warning` annotations right on the PR diff and in the\nrun log, with zero code-scanning setup (capped at GitHub's 10-per-type\ndisplay limit; the rest are summarized in one notice). Set\n`annotate: \"false\"` to turn it off. On the CLI, `gha-doctor --annotate`\nemits the same workflow commands after the report.\n\nCode scanning — `--sarif` findings as annotations in the Security tab:\n\n```yaml\n- uses: actions/checkout@v4\n- uses: linnea-bakshi/gha-doctor@v0\n with:\n args: --sarif > gha-doctor.sarif\n fail-on-findings: \"false\"\n- uses: github/codeql-action/upload-sarif@v3\n with:\n sarif_file: gha-doctor.sarif\n```\n\nShareable report — `--html` writes the whole report (findings, run history,\ntop wins, health score) as a single self-contained HTML file, no external\nassets or scripts — including two inline-SVG charts: every sampled run as a\nduration-over-time dot (green/red by outcome), and per-workflow p50→p95\n\"typical vs bad day\" range bars\n([live example, run against psf/requests](https://linnea-bakshi.github.io/gha-doctor/sample-report.html)).\nPublish it as a build artifact so anyone on the team can open it:\n\n```yaml\n- uses: linnea-bakshi/gha-doctor@v0\n with:\n args: --html gha-doctor.html\n fail-on-findings: \"false\"\n- uses: actions/upload-artifact@v4\n with:\n name: gha-doctor-report\n path: gha-doctor.html\n```\n\nInputs: `args` (default `--lint-only`), `version` (default: match the action\ntag, else latest), `github-token` (default: workflow token), `summary`,\n`pr-comment`, `baseline`, `fail-on-findings`, `fail-on` — the severity\nthat gates exit 2 (`any` | `warning` | `never`, passed as `--fail-on`; needs\nv0.48.0+, skipped with a note on older pins) — and `min-score` — fail when\nthe health score is below a threshold (passed as `--min-score`; needs\nv0.61.0+; combine with `fail-on: \"never\"` to gate on score alone). The binary stays on `PATH` for later steps in the same\njob. Pin `@v0` for the latest 0.x, or an exact tag like `@v0.3.0` — the\nmatching binary version is installed automatically.\n\nComplete copy-paste setups — PR gate, weekly health report, README badge,\nSARIF/code scanning, Grafana metrics, whole-org fleet report — live on the\n[recipes page](https://linnea-bakshi.github.io/gha-doctor/recipes). Every\nworkflow there lints clean under gha-doctor itself (a test enforces it).\n\n## MCP server (let your AI agent run the doctor)\n\n`gha-doctor --mcp` runs as a [Model Context Protocol](https://modelcontextprotocol.io)\nstdio server, so Claude Code, Cursor, and other MCP clients can diagnose CI\nas part of a conversation: *\"why is CI slow on this repo?\"*, *\"which tests\nare flaky?\"*, *\"what would gha-doctor fix here?\"*. Full guide (all clients,\ntool arguments, token setup, safety model):\n[**MCP server docs**](https://linnea-bakshi.github.io/gha-doctor/mcp).\n\n```bash\n# Claude Code\nclaude mcp add gha-doctor -- gha-doctor --mcp\n```\n\n```jsonc\n// generic MCP client config\n{\n \"mcpServers\": {\n \"gha-doctor\": {\n \"command\": \"gha-doctor\",\n \"args\": [\"--mcp\"]\n }\n }\n}\n```\n\nSix tools, all **read-only** — the server reports and previews but never\nwrites (applying fixes stays an explicit `gha-doctor --fix` in your shell):\n\n| Tool | What it does |\n|------|--------------|\n| `analyze_repo` | full health report: lint + history + flaky/waste/cost + score + top wins |\n| `lint_repo` | static rules only, on any GitHub repo or a local directory (offline) |\n| `preview_fixes` | the exact `--fix` diff, applied nowhere |\n| `run_deep_dive` | one run: waterfall, step regressions, failing tests, log tail |\n| `org_overview` | fleet triage across an org's busiest repos |\n| `explain_rule` | full documentation for a rule ID |\n\nThe server inherits your environment: set `GITHUB_TOKEN` (or be logged in\nvia `gh`) for history analysis and log reading; local lint works offline.\nIt speaks both current MCP protocol eras (the `initialize` handshake and\nthe stateless 2026-07-28 revision) — verified against the official MCP\nInspector.\n\nIt's listed in the official [MCP Registry](https://registry.modelcontextprotocol.io)\nas [`io.github.linnea-bakshi/gha-doctor`](https://registry.modelcontextprotocol.io/v0/servers?search=gha-doctor),\nso registry-aware clients can also run it from the container image with no\ninstall: `docker run -i --rm ghcr.io/linnea-bakshi/gha-doctor:latest --mcp`\n(add `-e GITHUB_TOKEN` for history analysis; local-directory lint needs a\nnative install or a mount).\n\n## Static rules\n\n| ID | Severity | Checks for |\n|----|----------|------------|\n| D001 | warn | PR-triggered workflow without `concurrency` + `cancel-in-progress` (superseded runs keep burning minutes) — **auto-fixable** |\n| D002 | warn | job without `timeout-minutes` (default is 360 — one hang burns 6 hours) — **auto-fixable** |\n| D003 | warn | `setup-node` / `setup-python` / `setup-java` without the built-in `cache:` input — **auto-fixable** |\n| D004 | info | `checkout` with `fetch-depth: 0` (full-history clone) |\n| D005 | warn | cron schedules more frequent than every 15 minutes |\n| D006 | info | macOS (10x billing) / Windows (2x) runners on every push or schedule |\n| D007 | warn | `docker/build-push-action` without `cache-from` (rebuilds every layer, every run) |\n| D008 | info | `actions/cache` without `restore-keys` (any key miss = fully cold cache) — **auto-fixable** |\n| D009 | info | job-level `continue-on-error: true` (green-washed failures) |\n| D010 | info | artifact upload with default 90-day retention |\n| D011 | warn | matrix expanding to ≥20 jobs per trigger |\n| D012 | info | `npm install` instead of `npm ci` in CI — **auto-fixable** |\n| D013 | warn | unscoped `push` + `pull_request` double-trigger (every PR commit runs CI twice) |\n| D014 | info | cron at minute 0 (peak-load window; GitHub delays/drops top-of-hour schedules) — **auto-fixable** |\n| D015 | warn | action version GitHub has **shut down** (`upload/download-artifact@v1–v3`, `cache@v1–v2`) — the step fails at runtime, every run — **auto-fixable** (cache only; artifacts changed semantics in v4) |\n| D016 | warn | **retired** hosted runner label (`ubuntu-20.04`, `windows-2019`, `macos-13`, …) — the job cannot run; resolves `${{ matrix.os }}` too — **auto-fixable** (ubuntu only: same-arch bump to `ubuntu-24.04`; windows/macos targets are your call) |\n| D017 | info | **nothing updates your action pins** — no dependabot `github-actions` ecosystem, no renovate config (repo-level check; this is how repos end up on D015/D016) |\n| D018 | warn | **deprecated workflow commands** in `run:` steps — `::set-env`/`::add-path` (disabled 2020, error at runtime) and `::set-output`/`::save-state` (deprecation warning on every run, removal announced) — **auto-fixable** (rewrites simple `echo` lines to `$GITHUB_OUTPUT`-style environment files) |\n| D019 | warn | **deprecated Node runtime in the actions you publish** — `action.yml` declaring `runs.using: node12`/`node16` (runtimes already removed from runners) or `node20` (removal from runners announced for fall 2026: the action stops working, for everyone using it). Scans root/subdir/`.github/actions` manifests; composite-action steps get the D015 and D018 checks too |\n| D020 | warn | hosted runner label with an **announced retirement** — `ubuntu-22.04` (brownouts from Sept 17, 2026; gone April 17, 2027) and `macos-14` (brownouts since July 6, 2026; gone Nov 2, 2026). D016 on a countdown: migrate on your schedule, not during a brownout — **auto-fixable** (ubuntu only) |\n| D021 | info | scheduled workflow without a `github.repository` guard — fork owners who enable Actions get your crons too (failed secret lookups, bot spam in forks) |\n\nEvery rule comes with a one-line fix, and line numbers point at the exact spot in\nyour YAML. Full reference — what each rule checks, why it matters, examples —\nin [docs/rules.md](docs/rules.md), or offline via `gha-doctor --explain D004`.\n\n**Suppressing findings:** every rule is a heuristic, and your workflow may be\nthe exception. Silence a single finding with a comment on the flagged line (or\non its own line directly above):\n\n```yaml\n- uses: actions/checkout@v4\n with:\n fetch-depth: 0 # gha-doctor: ignore[D004] (semantic-release needs history)\n```\n\nA bare `# gha-doctor: ignore` silences every rule on that line; IDs are\ncase-insensitive. Turn a rule off everywhere with `--disable D004,D009`.\n`--fix` respects both — a suppressed finding is never auto-fixed.\n\n**Auto-fix:** `gha-doctor --fix` repairs D001–D003, D008, D012, D014 and D015 in place\nwith surgical line edits — your comments and formatting survive, unlike a YAML\nround-trip. It adds a `concurrency` block with `cancel-in-progress: true`, caps\njobs at `timeout-minutes: 30` (tune afterwards), picks the right `cache:` value\nfor `setup-node`/`python`/`java` by reading your lockfiles (`pnpm-lock.yaml` →\n`pnpm`, `poetry.lock` → `poetry`, `pom.xml` → `maven`, …), derives a\n`restore-keys` prefix when your cache key ends in `${{ hashFiles(...) }}`,\nrewrites bare `npm install` to `npm ci`, moves minute-0 crons to a stable\nhash-picked minute (same cadence, off the :00 peak), and bumps\n`actions/cache` pins that point at shut-down versions. Anything ambiguous — two lockfiles,\nflow-style YAML, `npm install ` (npm ci takes no package args), a cache\nkey it can't safely split — is skipped with a note instead of guessed at. D004\n(`fetch-depth: 0`) is deliberately *not* auto-fixed: whether a job needs full\nhistory is a question only you can answer. Nothing is written unless the result\nparses and the finding is actually gone.\n\n**Preview first:** `gha-doctor --diff` shows the exact unified diff `--fix`\nwould apply — colored in the terminal, ` ```diff `-fenced with `--md`, per-file\nstrings with `--json` — and writes nothing. It even works on repos you haven't\ncloned: `gha-doctor --repo psf/requests --diff` fetches the workflows (and the\nlockfiles list, so `cache:` detection still works) and prints the patch.\nThe output is a standard unified diff: redirect it to a file and it applies\ncleanly with `git apply` on a checkout of the same commit — e.g.\n`gha-doctor --repo apache/spark --diff > fixes.patch && git apply fixes.patch`\n(verified against apache/spark's 45 workflow files: the patch applies\nbyte-exact and every patched file stays valid YAML).\n\n## History analysis\n\nWith API access, gha-doctor samples your recent completed runs (default 100) and reports:\n\n- **Per-workflow health** — success rate, p50/p95 duration, average queue time.\n- **Flaky jobs** — jobs that both failed and succeeded on the *same head commit*\n (via reruns or duplicate runs), with flake rate and wasted minutes.\n- **Slowest steps** — where the p50 minutes actually go, aggregated across runs.\n- **Matrix balance** — a matrix job finishes when its slowest shard does, so an\n uneven split is pure PR-feedback latency (the bill doesn't change; your wait\n does). Groups with 3+ shards and 5+ clean runs are measured; the report names\n the straggler shard and the median minutes every run spends waiting on it.\n- **Duration trend** — is the build getting slower? Compares each workflow's\n p50 (successful runs only) between the older and newer half of the sample.\n Only measured with 12+ successes spanning 24+ hours, and only reported past\n both a 20% and a 1-minute shift; a 30%+ slowdown earns an \"investigate\" slot\n in the top wins ([honesty gates](docs/honesty.md)).\n- **Waste** — minutes spent on failed runs and retries, weighted by runner billing\n multipliers (Linux 1x, Windows 2x, macOS 10x), as a share of everything sampled.\n- **Zombie crons** — scheduled workflows whose recent runs are an unbroken\n failure streak: a cron failing on repeat with nobody watching. Reported when\n the streak reaches 5+ consecutive scheduled failures spanning 3+ days, with\n the estimated minutes and dollars it keeps burning per month while it fails.\n A success ends a streak; skipped/cancelled runs neither break nor extend it.\n (Live example the day this shipped: a daily housekeeping cron on a top-tier\n Python repo had been failing for 25+ straight days.)\n- **Superseded PR runs** — runs that a newer push to the same PR branch replaced\n *while they were still running*, split into cancelled-in-time (concurrency at\n work) vs. ran-to-completion-anyway, with the billable minutes burned after the\n replacing push arrived. This is exactly the waste `concurrency` +\n `cancel-in-progress` (D001, `--fix`) prevents — now with a dollar figure on it.\n Scoped to `pull_request` events only (auto-cancelling pushes to release\n branches is often wrong), grouped by head repo + branch so two forks with the\n same branch name can't fake a supersession, and failed/retried superseded runs\n stay in the waste bucket above — no double counting.\n- **PR feedback time** — how long a contributor waits between pushing to a PR\n and the *last* check finishing (median and p95, queue time included), and\n which workflow is the critical path: the one that finishes last on most\n pushes, with the median gap it adds after everything else — that gap is what\n speeding it up would actually cut. Only pushes whose full verdict arrived\n count: superseded, awaiting-approval, and later-re-run pushes are excluded\n ([honesty gates](docs/honesty.md)).\n- **Cost estimate** — what the sample would cost at GitHub's public pay-as-you-go\n rates ($0.008/min Linux, 2x Windows, 10x macOS), metered the way GitHub actually\n bills: **each job rounded up to the whole minute**. The round-up overhead is\n reported separately — a matrix of 30-second jobs quietly doubles its own bill.\n Self-hosted jobs are excluded (GitHub doesn't bill them). Public repos on\n standard runners are free; the estimate then reads as \"what this would cost on\n a private repo\".\n- **Cache checkup** — usage against the 10 GB per-repo limit (past which GitHub\n evicts oldest-first and your builds go cold), stale caches unused for 7+ days,\n and megabytes pinned to `refs/pull/*` — PR caches are unreachable from every\n other branch, so after merge they're pure dead weight crowding out live ones.\n- **Artifact checkup** — who uploads the storage weight and how long it's kept.\n Artifacts bill at $0.008/GB-day on private repos and default to 90-day\n retention, so a chunky per-run artifact quietly converges to a large steady\n state (upload rate × retention). Reports per-name producers from the most\n recent uploads, flags big producers still on the 90-day default (pair with\n rule D010), and projects steady-state GB and $/month — only when the sample\n spans enough days to make the rate honest.\n- **Top wins** — the report closes with a ranked to-do list: the handful of\n changes worth making, dollar-quantified where the sample supports it\n (\"Cut failures and retries — ~$28/mo\", \"Consolidate tiny jobs — ~$22/mo\",\n \"Stop double-running PR pushes\"), each pointing at its rule or at\n `--fix` when gha-doctor can apply the change itself. Monthly projections\n only happen when the run sample spans ≥3 days — below that you get honest\n sample totals and a note saying why.\n- **Flaky tests, by name** (`--flaky-logs N`) — flaky-*job* detection tells you\n *where* it hurts; this tells you *which test*. It reads the logs of up to N\n failed job runs whose commit also passed (the same-SHA fail+pass pairs from\n the flaky-jobs table) and extracts the failing tests using the frameworks'\n own failure summaries — [28 framework families](https://linnea-bakshi.github.io/gha-doctor/flaky-frameworks):\n pytest, Python unittest (incl. Django's runner), `go test`, `cargo test`,\n jest, vitest, playwright, Cypress, mocha, ava, rspec, minitest, phpunit, exunit,\n maven surefire, gradle (JUnit), sbt, .NET (xunit v3 / VSTest), XCTest\n (xcodebuild, `swift test`, and xcbeautify output), swift-testing, LLVM\n lit, meson test, GoogleTest, CTest, doctest, bazel, cargo-nextest, and node-core test.py — including tests that run\n inside `docker build` (BuildKit's log prefix is stripped). Output is ranked by how many sampled\n logs each test failed in, with distinct commits and jobs alongside — and the\n top offender is named in **Top wins** (live example from psf/requests:\n `tests/test_requests.py::TestRequests::test_pyopenssl_redirect`). Unrecognized\n failures say so honestly rather than guessing — a build error is not a flaky\n test. When a flaky run's logs speak no recognized format, its uploaded\n **test-report artifacts (JUnit XML / .NET TRX / NUnit3 / TestNG)** are consulted as a fallback (only when\n every failed job in that run was itself flaky-proven — a genuinely broken\n sibling job must not read as flaky; run-level attribution, own subsection).\n Needs auth, like everything that downloads logs.\n- **Cache hit rate** (`--cache-logs N`) — the API never tells you whether caches\n actually *hit*; the only place that's recorded is the log text. This samples N\n recent job logs (one API request each, spread round-robin across job names so\n a chatty matrix doesn't crowd out the rest) and parses the cache markers that\n `actions/cache`, `setup-go`, `setup-node` & friends emit: exact hits, partial\n hits via `restore-keys`, misses, megabytes downloaded — grouped by key pattern\n with hashes collapsed (`Linux-go-4ae0e4f8… → Linux-go-*`). It also counts cache\n saves that lost a \"unable to reserve cache\" race — concurrent jobs silently\n rebuilding the same key. Needs auth: log downloads 403 without a token even on\n public repos.\n\n## Single-run deep dive (`--run`)\n\n\"Why was *this* run slow?\" — point `--run` at a run ID, a pasted run URL, or\n`latest`, and get the one run dissected:\n\n- **A job waterfall** on the run's wall clock: queue wait (`·`) vs execution\n (`█`), colored by conclusion, so parallelism gaps and runner starvation are\n visible at a glance.\n- **Step timings vs the workflow's own history** — every job and step is\n compared against its median in the last 8 successful runs of the same\n workflow. The verdict names the regressions: `⚠ \"Install dependencies\" in\n build (3.12, windows-latest): +59s vs its p50 (3.7x slower)`.\n- **Failed runs lead with where they failed** (`✗ job \"lint\" failed at step\n \"golangci-lint\"`) — and are never praised for \"finishing fast\".\n- **The failing step's log tail, right in the report** (authenticated runs):\n the last 20 lines of the failing step — sliced out of the job log by the\n step's own timestamps, anchored on the `##[error]` marker, cleanup chatter\n trimmed — so the actual compiler error or `--- FAIL` line is on screen\n without clicking through the Actions UI. Tune with `--log-tail N`\n (0 turns it off).\n- **The failing tests, by name** (authenticated runs): the job log is run\n through the same [28 framework extractors](https://linnea-bakshi.github.io/gha-doctor/flaky-frameworks)\n that power `--flaky-logs`, so a red run's verdict reads `✗ job \"test\n (3.12)\" failed at step \"pytest\" — 3 failing tests incl.\n tests/test_retry.py::test_backoff` instead of making you scroll the log.\n Build and infra failures extract nothing by design — no recognized\n test-failure output means no test names, not guessed ones.\n- **Test-report artifacts as the fallback (JUnit XML / TRX / NUnit3 / TestNG)** (authenticated runs):\n when the failed jobs' console output speaks no recognized format, the\n run's uploaded artifacts are checked for JUnit XML reports (`pytest\n --junitxml`, surefire, Gradle, jest-junit, `ctest --output-junit`, …),\n .NET TRX files (`dotnet test --logger trx`), NUnit3 reports\n (`nunit3-console`, `dotnet test --logger nunit`, Unity's test runner) or\n native TestNG results (`testng-results.xml` — selenium-style automation\n suites often upload only that) and\n the failing tests are named from those — exact names for *any* framework\n that writes the industry-standard report file. Listed at run level with\n the source artifact named, because artifacts belong to the run, not to\n one job — attribution never pretends otherwise.\n- **Re-runs are understood:** attempt numbers, jobs that ran again vs results\n carried over from earlier attempts, with the billing consequence spelled out.\n- The usual honesty gates: fewer than 3 comparable successful runs and the\n comparisons are dropped with a note, not faked. In-progress runs say \"so\n far\" instead of getting a verdict.\n\nWorks with `--json` and `--md` too (`gha-doctor --repo owner/name --run latest --md`\npastes straight into an incident issue).\n\n## Health score & badge\n\nEverything measured is condensed into a 0–100 **CI health score** (A+–F),\nitemized so you can see exactly where the points went:\n\n```text\nHealth score\n F (54/100, run history only)\n ✗ success rate −17.5 72% of 100 sampled runs succeeded\n ! queue time −0.3 average 6 s waiting for a runner\n ! flakiness −5 1 job failed AND passed on the same commit\n ! wasted minutes −4.1 8% of sampled compute minutes went to failed runs or retries\n ✗ cache pressure −5 cache storage at 101% of the 10 GB limit (evictions likely)\n```\n\n`--badge health.svg` writes a shields-style SVG of the grade for your\nREADME, and a tiny scheduled workflow can keep it fresh.\n`--score-history scores.jsonl` records each run to a committable JSONL\nfile and prints the delta since last time (`Δ +7 since 2026-07-22 (B 84 →\nA 91)`), including which components improved or regressed. Use both flags\ntogether and the badge gains a sparkline of your recent scores — the\ntrend at a glance, next to your build badge. Weights,\nformula, trend tracking, and the badge workflow are documented in\n[docs/score.md](docs/score.md).\n\n## Prometheus / Grafana (`--prom`)\n\n```sh\ngha-doctor --prom ci-health.prom # alongside the normal report\n```\n\n`--prom` writes every measured aggregate — health score, findings by\nseverity, per-workflow success ratios and p50/p95 durations, queue time,\nwasted and rounded-up compute (seconds and USD), flaky jobs, zombie\ncrons, cache size against the 10 GB limit, superseded-run waste, PR\nfeedback time — in the Prometheus text exposition format. Run it on a\nschedule and CI health becomes a Grafana dashboard with real history,\nnot a point-in-time report. A ready-made dashboard (health score gauge,\nwaste and duration trends, cache vs the 10 GB limit, per-repo template\nvariable) ships in the docs — see\n[docs/grafana.md](https://linnea-bakshi.github.io/gha-doctor/grafana),\nverified against a live Grafana + Prometheus stack.\n\nTwo easy wirings:\n\n- **Textfile collector** (self-hosted runner or any box with\n node_exporter): write the file into the collector's directory —\n `gha-doctor --prom /var/lib/node_exporter/textfile/gha-doctor.prom`.\n- **Pushgateway** (hosted runners): a scheduled workflow pushes the\n export —\n\n ```yaml\n - run: |\n gha-doctor --fail-on never --prom metrics.prom\n curl --data-binary @metrics.prom \\\n https://pushgateway.example.com/metrics/job/gha-doctor/instance/${{ github.repository_owner }}-${{ github.event.repository.name }}\n ```\n\nHonesty carries over: anything the run didn't measure emits **no series\nat all** (a gap on the dashboard is the truth; a zero-filled series\nwould be a lie), while a measured zero — zero flaky jobs across a\nsampled window — is a real `0`. Every value is a gauge describing the\nsampled window; `gha_doctor_sample_since_timestamp_seconds` says how far\nback that window reaches, and `gha_doctor_last_run_timestamp_seconds` is\nthere to alert on staleness.\n\n## Org-wide triage (`--org`)\n\n```sh\ngha-doctor --org yourorg # 20 most recently pushed repos, 100 runs each\ngha-doctor --org yourorg --max-repos 50 --md # bigger fleet, Markdown for an issue\n```\n\nOne screen for the whole org: per-repo run volume, failure rate, p50/p95\nduration, and estimated wall-clock run minutes per 30 days — sorted by who's\nburning the most. Works for user accounts too, and skips forks and archived\nrepos automatically. It also names **zombie crons anywhere in the fleet** —\nscheduled workflows whose sampled runs are an unbroken failure streak (same\ngates as the repo-level check), spotted from the run samples already fetched\nat zero extra API cost. Dead lock-issues bots and broken nightlies quietly\ninflate a repo's fail rate for months; the fleet view points straight at\nthem. No `$`/month projection here — the org scan never fetches job data, so\npricing would be a guess; drill in with `--repo` for the billable burn.\n\nIt's deliberately cheap: **one API request per repo** (run-level data only), so\na 50-repo org costs ~51 requests instead of thousands. That also means the\nminutes shown are wall-clock per run, not billable job minutes — parallel jobs\neach bill in full — so treat it as a triage view: find the loudest repo, then\ndrill in with `--repo org/name` for exact per-job billing, flaky jobs, and\ncache health.\n\n### Fleet card (`--org` + `--svg`)\n\n```sh\ngha-doctor --org yourorg --svg fleet.svg\n```\n\nwrites the fleet table as a self-contained SVG card you can embed in an org\nprofile README or a dashboard (busiest 12 repos + aggregate tail; regenerate it\nfrom a scheduled workflow the same way as the [score badge](docs/score.md)):\n\n\n\n## Comparison\n\n| | actionlint | zizmor | **gha-doctor** |\n|---|---|---|---|\n| Focus | correctness | security | **speed / cost / reliability** |\n| Static workflow checks | ✅ | ✅ | ✅ (perf & cost rules) |\n| Uses your run history | ❌ | ❌ | ✅ |\n| Flaky-job detection | ❌ | ❌ | ✅ |\n| Wasted-minutes estimate | ❌ | ❌ | ✅ |\n| $ cost estimate (incl. round-up) | ❌ | ❌ | ✅ |\n| Cache-limit / stale-cache checkup | ❌ | ❌ | ✅ |\n| Cache hit-rate measurement (from logs) | ❌ | ❌ | ✅ |\n| Artifact storage / retention checkup | ❌ | ❌ | ✅ |\n\nThey compose: run all three. For a detailed, honest breakdown — including\nwhere the three tools *overlap* — see\n[gha-doctor vs actionlint vs zizmor](https://linnea-bakshi.github.io/gha-doctor/comparison).\n\n## License\n\nMIT © Linnea Bakshi\n",
"bytes": 41252,
"sha": "14a1fda47a2bfad86260f976556901fe6a760a785ddc2b85877a522213e75ecf",
"repo_slug": "linnea-bakshi/gha-doctor",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_linnea_bakshi_gha_doctor_94b52129/readme"
}