Wezylnia/gha-cache-doctor

# gha 缓存医生 [](https://github.com/Wezylnia/gha-cache-doctor/actions/workflows/ci.yml) [](https://github.com/Wezylnia/gha-cache-doctor/releases) [](LICENSE) 一个专注于扫描 GitHub Actions 工作流程中缓存配置错误、弱缓存键和错过依赖缓存机会的 .NET CLI 工具。 `gha-cache-doctor` 是一个精炼的 MVP，并且故意保持小巧。如果你喜欢 CI/CD 工具、静态分析或从缓慢的管道中节省时间，那么有适合贡献者的良好入门问题。 ## 30 秒内尝试 ``` dotnet restore dotnet run --project src/GhaCacheDoctor.Cli -- scan --path samples/github-actions/bad --fail-on none ``` JSON 输出： ``` dotnet run --project src/GhaCacheDoctor.Cli -- scan --path samples/github-actions/bad --format json --fail-on none ``` ## 为什么存在 GitHub Actions 缓存看起来很简单，但缓存配置很容易出错。工作流程可能会在每次运行时安装依赖项，使用一个永远不会正确失效的缓存键，或者完全错过 monorepo 锁文件。 `gha-cache-doctor` 专注于缓存质量。它不替代通用工作流程检查器。相反，它提供对包管理器感知的发现和改进 CI 缓存行为的实用建议。 ## 状态 当前版本：`0.2.0` 该项目已准备好本地使用和公开贡献。CLI、解析器、报告器、严格模式行为、初始规则、测试、示例工作流程和贡献者文档都已就绪。请参阅 [docs/project-status.md](docs/project-status.md) 和 [docs/roadmap.md](docs/roadmap.md). 寻找帮助的地方？从这里开始： - [良好入门问题](https://github.com/Wezylnia/gha-cache-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22) - [需要帮助](https://github.com/Wezylnia/gha-cache-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22) - [规则请求](https://github.com/Wezylnia/gha-cache-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3Arule) ## 要求 - .NET SDK 10 ## 安装 对于本地打包： ``` dotnet pack src/GhaCacheDoctor.Cli --configuration Release dotnet tool install --tool-path .tmp/tools gha-cache-doctor --version 0.2.0 --add-source src/GhaCacheDoctor.Cli/bin/Release .tmp/tools/gha-cache-doctor scan --path samples/github-actions/bad --fail-on none ``` 在发布公共包后： ``` dotnet tool install --global gha-cache-doctor --version 0.2.0 gha-cache-doctor scan ``` ## 快速入门 扫描默认工作流程目录： ``` dotnet run --project src/GhaCacheDoctor.Cli -- scan ``` 扫描特定工作流程目录： ``` dotnet run --project src/GhaCacheDoctor.Cli -- scan --path .github/workflows ``` 在警告或错误时失败 CI： ``` dotnet run --project src/GhaCacheDoctor.Cli -- scan --fail-on warning ``` ## 示例输出 ``` samples/github-actions/bad/weak-cache-key.yml [warning] GHA-CACHE003 actions-cache-key-missing-lockfile-hash Job: test Step: Cache npm actions/cache uses a dependency cache path, but the key does not include a lockfile hash. Recommendation: Include a dependency lockfile hash, for example `${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}`. ``` ## 规则 | 规则 | 严重性 | 类别 | 描述 | |---|---:|---|---| | [`GHA-CACHE001`](docs/rules/GHA-CACHE001-setup-node-cache-missing.md) | info | performance | 报告 `actions/setup-node` 使用时没有依赖缓存的情况。 | | [`GHA-CACHE002`](docs/rules/GHA-CACHE002-setup-node-cache-dependency-path-missing.md) | warning | performance | 报告在可能为 monorepo 的情况下使用 `setup-node` 缓存而没有 `cache-dependency-path`。 | | [`GHA-CACHE003`](docs/rules/GHA-CACHE003-actions-cache-key-missing-lockfile-hash.md) | warning | correctness | 报告依赖缓存键不包含锁文件哈希的依赖缓存。 | | [`GHA-CACHE004`](docs/rules/GHA-CACHE004-restore-keys-too-broad.md) | info | maintainability | 报告过于宽泛的 `restore-keys`，可能会恢复无关的缓存。 | | [`GHA-CACHE005`](docs/rules/GHA-CACHE005-install-step-without-cache.md) | info | performance | 报告似乎没有匹配缓存的依赖项安装步骤。 | 想要添加下一个规则？规则系统故意很简单：一个小类、专注的测试、一个文档页面和一个 README 表格更新。请参阅 [Adding a Rule](docs/contributing/adding-a-rule.md). 需要实用的缓存键模式？请参阅 [Cache Key Cookbook](docs/cache-key-cookbook.md)，其中包含跨常见包管理器和 Docker BuildKit 的前后示例。 ## CLI 参考 ``` gha-cache-doctor scan [options] Options: --repo Repository root. Defaults to current directory. --path Workflow file or directory. Defaults to .github/workflows. --format Output format. Defaults to text. --fail-on --include Comma-separated rule IDs to include. --exclude Comma-separated rule IDs to exclude. --strict Enable stricter rule behavior. --config Config file. Defaults to .gha-cache-doctor.yml if present. -h, --help Show help. ``` ## 配置 `gha-cache-doctor` 在存在时自动从存储库根目录读取 `.gha-cache-doctor.yml` 或 `.gha-cache-doctor.yaml`。使用 `--config ` 选择文件或使用 `--config none` 禁用配置加载。 ``` path: .github/workflows format: text failOn: warning strict: true exclude: - GHA-CACHE004 severity: GHA-CACHE005: warning ``` CLI 选项优先于配置值。请参阅 [Configuration](docs/configuration.md) 获取完整参考。 退出代码： ``` 0 = no findings at or above the fail threshold 1 = findings exist at or above the fail threshold 2 = invalid CLI usage 3 = workflow parse error ``` ## JSON 输出 ``` dotnet run --project src/GhaCacheDoctor.Cli -- scan --format json ``` JSON 架构故意很简单且稳定，以便 CI 消费： ``` { "findings": [ { "ruleId": "GHA-CACHE003", "severity": "warning", "category": "correctness", "message": "actions/cache uses a dependency cache path, but the key does not include a lockfile hash.", "recommendation": "Include a dependency lockfile hash, for example `${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}`.", "filePath": ".github/workflows/ci.yml", "line": 10, "jobId": "test", "stepName": "Cache npm" } ], "parseErrors": [] } ``` ## GitHub Actions 使用 ``` - name: Check GitHub Actions cache configuration run: dotnet run --project src/GhaCacheDoctor.Cli -- scan --fail-on warning ``` 一旦作为工具安装： ``` - name: Install gha-cache-doctor run: dotnet tool install --global gha-cache-doctor --version 0.2.0 - name: Check cache configuration run: gha-cache-doctor scan --fail-on warning ``` ## 开发 ``` dotnet restore dotnet build GhaCacheDoctor.slnx dotnet test GhaCacheDoctor.slnx ``` 在本地运行 CLI： ``` dotnet run --project src/GhaCacheDoctor.Cli -- scan --path samples/github-actions/bad --fail-on none ``` ## 贡献 贡献非常欢迎。该项目具有小范围、清晰的规则边界和确定性的测试，因此是改进 CI/CD 工具的好地方。 良好的贡献路径： - 为你使用的包管理器添加缓存规则。 - 改进 monorepo 识别和建议。 - 添加报告器输出，如 SARIF 或 GitHub 注释。 - 从真实工作流程添加解析器或误报测试。 - 通过工作流程示例改进文档。 从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始。对于规则更改，请参阅 [docs/contributing/adding-a-rule.md](docs/contributing/adding-a-rule.md). 开放贡献队列： - [适合初学者](https://github.com/Wezylnia/gha-cache-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22beginner%20friendly%22) - [可以抢夺](https://github.com/Wezylnia/gha-cache-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22up%20for%20grabs%22) - [高影响](https://github.com/Wezylnia/gha-cache-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22high%20impact%22) ## 路线图 - [项目状态](docs/project-status.md) - [路线图](docs/roadmap.md) - [发布清单](docs/release-checklist.md) - [规则目录](docs/rules/README.md) ## 存储库治理 公共存储库已设置为接受小型、可审查的贡献。问题已标记为规则工作、输出格式、适合初学者的任务和高影响改进。拉取请求应包括对用户可见行为更改的测试和文档。 `main` 分支受到所需 CI、代码所有者审查、过时审查取消、最后推送批准、对话解决和禁用强制推送/删除的保护。存储库管理员保留紧急绕过能力。为针对 `main` 的拉取请求启用了 GitHub Copilot 自动 PR 审查。 在合并之前需要维护者审查，并且依赖项更新 PR 应在发布工作之前保持 CI 绿色。 ## 许可证 MIT。请参阅 [LICENSE](LICENSE).

标签：Automation, Cache Key, Cache Misconfiguration, CI Pipeline, Code Analysis, Code Efficiency, Code Linters, Code Maintenance, Code Optimization, Code Optimization Tools, Code Quality, Code Review, Dependency-Cache, Dependency Management, Developer Tools, GitHub Actions, GitHub Actions Caching, MIT License, .NET CLI, Open Source, Performance Improvement, Security Best Practices, Software Development, Static Analysis, Workflows, 多人体追踪, 自动笔记