gha-doctor

gha-doctor is a command-line tool that diagnoses GitHub Actions workflows for flaky jobs, wasted minutes, slow steps, cache problems and workflow anti-patterns in one command with zero configuration. The README positions it alongside actionlint (correctness) and zizmor (security) as covering speed, cost and reliability. It reads .github/workflows for static checks and uses an existing GITHUB_TOKEN or gh CLI authentication for run-history analysis; a lint-only mode works offline with no auth. A --repo owner/name flag fetches another repository's workflow files and run history through the API, so repos do not need to be cloned, and --org runs fleet triage across an organisation or user. Static analysis is organised into 21 documented rules (D001 to D021) with severities and line numbers pointing at the exact YAML location. They cover things such as missing concurrency with cancel-in-progress on pull-request workflows, jobs without timeout-minutes, setup-node/setup-python/setup-java without the built-in cache input, full-history checkouts, crons more frequent than every 15 minutes, macOS and Windows runners on every push, docker build-push without cache-from, actions/cache without restore-keys, job-level continue-on-error, default artifact retention, large matrices, npm install instead of npm ci, unscoped push plus pull_request double triggers, cron at minute 0, shut-down or retired runner labels and action versions, missing automated action pin updates, deprecated workflow commands, deprecated Node runtimes in published actions, and scheduled workflows without a repository guard. Findings can be silenced inline with a comment on the flagged line or globally with --disable, and each rule can be explained offline with --explain. Run-history analysis detects flaky jobs by looking for jobs that both failed and passed on the same commit, reports per-workflow success rate, p50 and p95 durations, queue time and cost, identifies slowest steps and wasted minutes, and can measure cache hit and miss rates and name flaky tests from job logs. Everything measured rolls up into an itemised 0 to 100 health score that can be written as an SVG badge. Output formats include plain text, machine-readable JSON with published JSON Schemas, Markdown, SARIF 2.1.0, inline annotation workflow commands, and a self-contained HTML report with inline charts. An auto-fix mode applies surgical line edits for the fixable rules, with a separate diff mode to preview changes without writing. A repository config file in .gha-doctor.yml or .github/gha-doctor.yml states policy such as disabled rules, history sample size, log sampling and failure thresholds; explicit CLI flags take precedence and a no-config flag ignores it. Exit code 2 signals warnings so the tool can gate CI, with configurable severity gating and a minimum health score threshold. The project also ships as a composite GitHub Action that installs the release binary and supports inputs for args, version, token, job summary, sticky pull-request comments, baseline diffing against a base branch, and failure thresholds; inline annotations are on by default. GitHub Enterprise Server is supported through the GH_HOST variable. A Model Context Protocol stdio server mode exposes six read-only tools (analyze_repo, lint_repo, preview_fixes, run_deep_dive, org_overview, explain_rule) so MCP clients can query CI health; the server is listed in the official MCP Registry and can also run from the container image. Installation options include a gh CLI extension, Homebrew, Scoop, a distroless multi-arch Docker image, go install, aqua, mise/ubi, asdf, release binaries, deb/rpm/apk packages, shell completions and pre-commit hooks. A browser playground runs the linter and its auto-fixes client-side via WebAssembly. The README states the project is built and maintained by an AI agent and that the tool only ever reads from repositories; private-repo use needs Actions read and Contents read permissions.