gha-doctor

gha-doctor 是一款命令行工具，只需一条命令且无需任何配置，即可诊断 GitHub Actions 工作流中的不稳定任务（flaky jobs）、浪费的时间、缓慢的步骤、缓存问题以及工作流反模式。其 README 将其与 actionlint（正确性）和 zizmor（安全性）并列，旨在覆盖速度、成本和可靠性。它读取 .github/workflows 进行静态检查，并使用现有的 GITHUB_TOKEN 或 gh CLI 身份验证来进行运行历史分析；仅 Lint 模式支持离线运行，无需身份验证。--repo owner/name 标志可以通过 API 获取另一个仓库的工作流文件和运行历史，因此无需克隆仓库，而 --org 则可以在整个组织或用户范围内运行批量分类诊断。 静态分析被组织为 21 个已记录的规则（D001 到 D021），带有严重程度和指向确切 YAML 位置的行号。这些规则涵盖了诸如：在拉取请求（pull-request）工作流中缺失带有 cancel-in-progress 的并发控制、没有设置 timeout-minutes 的任务、未使用内置缓存输入的 setup-node/setup-python/setup-java、完整历史检出（full-history checkouts）、频率高于每 15 分钟一次的 cron 定时任务、每次推送都运行 macOS 和 Windows 运行器、没有 cache-from 的 docker build-push、没有 restore-keys 的 actions/cache、任务级别的 continue-on-error、默认的构建产物保留期、大型矩阵、使用 npm install 而非 npm ci、未限制范围的 push 加上 pull_request 双重触发、在第 0 分钟运行的 cron、已停用或退役的运行器标签和 action 版本、缺失自动化的 action 版本锁定（pin）更新、已废弃的工作流命令、已发布的 action 中已废弃的 Node 运行时，以及没有仓库保护（repository guard）的定时工作流。发现的问题可以通过在被标记行上添加注释来进行行内忽略，也可以使用 --disable 进行全局禁用，并且每个规则都可以通过 --explain 进行离线解释。 运行历史分析通过寻找在同一提交上既失败又通过的任务来检测不稳定任务，报告每个工作流的成功率、p50 和 p95 持续时间、排队时间和成本，识别最慢的步骤和浪费的时间，并能测量缓存命中和未命中率，以及从任务日志中识别出不稳定的测试。所有测量指标都会汇总为一个 0 到 100 分的逐项健康评分，该评分可以写入为 SVG 徽章。输出格式包括纯文本、带有已发布 JSON Schema 的机器可读 JSON、Markdown、SARIF 2.1.0、行内注解工作流命令，以及带有内嵌图表的独立 HTML 报告。 自动修复模式可针对可修复的规则进行精准的行编辑，并提供独立的 diff 模式以在不写入的情况下预览更改。位于 .gha-doctor.yml 或 .github/gha-doctor.yml 的仓库配置文件可声明策略，例如禁用的规则、历史样本大小、日志采样和失败阈值；显式的 CLI 标志具有更高优先级，而 no-config 标志则会忽略该配置。退出代码 2 表示警告，以便该工具可以作为 CI 的门禁，并支持可配置的严重程度门禁和最低健康评分阈值。 该项目还作为一个组合式 GitHub Action 提供，用于安装发布版本二进制文件，并支持 args、version、token、任务摘要、置顶拉取请求评论、与基线分支的基线对比以及失败阈值等输入；行内注解默认开启。通过 GH_HOST 变量支持 GitHub Enterprise Server。Model Context Protocol（MCP）stdio 服务器模式公开了六个只读工具（analyze_repo、lint_repo、preview_fixes、run_deep_dive、org_overview、explain_rule），以便 MCP 客户端可以查询 CI 健康状况；该服务器已列入官方 MCP 注册表（MCP Registry），也可以从容器镜像中运行。 安装选项包括 gh CLI 扩展、Homebrew、Scoop、distroless 多架构 Docker 镜像、go install、aqua、mise/ubi、asdf、发布版二进制文件、deb/rpm/apk 包、shell 补全和 pre-commit 钩子。浏览器游乐场（playground）通过 WebAssembly 在客户端运行 Linter 及其自动修复功能。README 指出，该项目由 AI 智能体构建和维护，且该工具仅对仓库进行读取操作；在私有仓库中使用需要 Actions 读取和 Contents 读取权限。