gha-doctor 是一款专注于 GitHub Actions 速度、成本与可靠性的诊断工具。它由 AI 代理 Linnea Bakshi 构建和维护，采用只读方式运行，不会修改仓库内容。与 actionlint（检查正确性）和 zizmor（检查安全性）不同，gha-doctor 覆盖了此前未被开源工具覆盖的第三方面：速度、成本和可靠性。
用途
gha-doctor 旨在帮助开发者发现 GitHub Actions 工作流中的低效与问题，包括：
- 不稳定任务（flaky jobs）：同一提交上既失败又成功的任务，会浪费可计费分钟。
- 成本问题：缺少并发取消、未缓存依赖安装、每次推送都使用昂贵的 macOS 运行器、默认 6 小时超时、全历史检出等。
- 缓慢步骤：聚合分析各步骤的耗时分布。
- 缓存问题：检测缓存配置不当或未命中。
- 工作流反模式：静态检查 YAML 中的常见错误配置。
主要能力
- 零配置：在仓库内运行即可，读取
.github/workflows/进行静态检查，使用现有GITHUB_TOKEN或ghCLI 认证进行历史分析。 - 健康评分：所有测量结果汇总为 0–100 的逐项健康评分，可通过
--badge生成 SVG 徽章。 - 远程仓库支持：
--repo owner/name可通过 API 获取未克隆仓库的工作流文件和运行历史。 - 历史分析：采样最近完成的运行（默认 100 次），报告每个工作流的成功率、p50/p95 时长、平均排队时间、不稳定任务及其浪费分钟、最慢步骤、矩阵平衡等。
- 自动修复：
--fix可修复 D001–D003、D008、D012、D014 和 D015 规则，进行精准行编辑，保留注释和格式。 - 修复预览：
--diff显示--fix将应用的统一差异，不写入任何内容。 - 多种输出格式：支持
--json、--sarif、--html、--md等。 - MCP 服务器：
--mcp以 Model Context Protocol stdio 服务器运行，供 Claude Code、Cursor 等 MCP 客户端在对话中诊断 CI。 - GitHub Action：可作为复合 Action 使用，支持 PR 评论、内联注解、代码扫描、基线对比等。
使用方式
安装方式包括：
- gh CLI 扩展：
gh extension install linnea-bakshi/gha-doctor - Homebrew（macOS / Linux）
- Scoop（Windows）
- Docker（多架构）：
docker run -i --rm ghcr.io/linnea-bakshi/gha-doctor:latest --mcp - aqua、mise / ubi、asdf
- 从 releases 页面下载二进制文件（linux/macOS/windows，amd64/arm64），以及 .deb、.rpm、.apk 包
基本用法：在仓库内运行 gha-doctor 即可。--lint-only 无需认证。历史分析需要设置 GITHUB_TOKEN 或使用 gh CLI 登录。
作为 GitHub Action 使用：gha-doctor --init 可生成一个可提交的 .github/workflows/gha-doctor.yml，在每次 PR 时进行 lint，仅对 PR 引入的问题进行门禁（baseline: auto），并发布粘性评论和内联注解。
适用场景
- 希望降低 GitHub Actions 账单的团队。
- 需要识别和修复不稳定测试的开发者。
- 希望在工作流中引入 CI 健康门禁的项目。
- 需要为仓库添加 CI 健康徽章的开源项目。
- 使用 MCP 客户端（如 Claude Code、Cursor）进行 CI 诊断的 AI 辅助工作流。
- GitHub Enterprise Server 环境（通过
GH_HOST等环境变量支持）。
限制
- 工具仅读取，不写入；自动修复需显式运行
--fix。 - 成本估算使用 github.com 托管运行器定价，自托管运行器（GHES 常见）已排除在成本计算之外，因此 GHES 上通常显示基于时间的发现而非美元数字。
- 部分规则（如 D004
fetch-depth: 0）故意不自动修复，因为是否需要完整历史取决于用户判断。 - 自动修复会跳过模糊情况（如两个锁文件、流式 YAML、带参数的
npm install等），并给出说明而非猜测。 - 退出码：0 表示干净或仅信息，2 表示发现警告，可用于 CI 门禁。
- 私有仓库需要令牌具有 Actions: read 和 Contents: read 权限。
- 文档站点、规则参考、配方、FAQ 等更多信息请访问 https://linnea-bakshi.github.io/gha-doctor。
