Wezylnia/gh-actions-doctor
GitHub: Wezylnia/gh-actions-doctor
gh-actions-doctor：GitHub Actions工作流程安全与性能分析工具
Stars: 1 | Forks: 2
# gh-actions-doctor -> gh-actions-doctor
[](https://github.com/Wezylnia/gh-actions-doctor/actions/workflows/ci.yml)
[](https://github.com/Wezylnia/gh-actions-doctor/releases)
[](LICENSE)
一个轻量级的 .NET CLI，用于扫描 GitHub Actions 工作流程中的安全问题、可靠性、性能和成本问题。
## 30 秒内尝试
```
git clone https://github.com/Wezylnia/gh-actions-doctor.git
cd gh-actions-doctor
dotnet run --project src/GhActionsDoctor.Cli -- scan --path samples/bad --fail-on none
```
## 为什么存在
GitHub Actions 工作流程通常被从项目复制到项目，然后闲置数月。它们可能仍然可以工作，但小问题会不断积累：
- 过于宽泛的 `GITHUB_TOKEN` 权限，
- 引用可变分支如 `@main` 的操作，
- 未固定到提交 SHA 的第三方操作，
- 风险的 `pull_request_target` 使用，
- 没有时限的任务，
- 没有并发控制的流程，
- 没有缓存的依赖安装，
- 过于宽泛的触发器，无谓地消耗 CI 分钟。
`gh-actions-doctor` 早期捕捉这些问题，并打印实用的建议。
## 状态
当前版本：`0.2.0`
此存储库包含精炼的 MVP。它可以扫描工作流程文件，以文本或 JSON 格式报告发现，提高更严格的安全发现，并返回 CI 友好的退出代码。
寻找帮助的地方？从这里开始：
- [良好的入门问题](https://github.com/Wezylnia/gh-actions-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
- [需要帮助](https://github.com/Wezylnia/gh-actions-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22)
- [规则请求](https://github.com/Wezylnia/gh-actions-doctor/issues?q=is%3Aissue%20is%3Aopen%20label%3Aarea%3Arules)
## 要求
- .NET SDK 10
此项目目前针对 `net10.0`。
## 安装
当前包版本为 `0.2.0`。
当发布到 NuGet：
```
dotnet tool install --global gh-actions-doctor --version 0.2.0
```
从本地打包的包：
```
dotnet pack src/GhActionsDoctor.Cli --configuration Release
dotnet tool install --tool-path .tmp/tools gh-actions-doctor --version 0.2.0 --add-source src/GhActionsDoctor.Cli/bin/Release
.tmp/tools/gh-actions-doctor scan
```
## 快速入门
扫描默认工作流程目录：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan
```
扫描自定义目录：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --path samples/bad
```
打印 JSON：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --path samples/bad --format json
```
在警告或错误上失败构建：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --fail-on warning
```
仅运行选定的规则：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --include missing-permissions,missing-timeout
```
跳过选定的规则：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --exclude action-not-sha-pinned
```
严格模式提高选定的安全发现：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --strict
```
## 示例输出
```
GitHub Actions Doctor
Scanned workflows: 2
build.yml
[warning] Workflow does not define a top-level permissions block. (missing-permissions)
Suggestion: Add a top-level permissions block and grant only the permissions required by the workflow.
[warning] Job 'build' does not define timeout-minutes. (missing-timeout)
Suggestion: Add a timeout-minutes value that reflects the expected maximum runtime for this job.
[info] actions/setup-node is used without dependency caching. (setup-node-cache-missing)
Suggestion: Add a cache value such as npm, yarn, or pnpm when the workflow installs Node.js dependencies.
Summary:
0 errors
2 warnings
1 info
```
## 规则
| 规则 | 严重性 | 类别 | 描述 |
| --- | --- | --- | --- |
| [`missing-permissions`](docs/rules/missing-permissions.md) | 警告 | 安全 | 报告没有顶级 `permissions` 块的工作流程。 |
| [`mutable-action-reference`](docs/rules/mutable-action-reference.md) | 警告 | 安全 | 报告使用可变引用的操作，如 `@main`、`@master` 或 `@latest`。 |
| [`action-not-sha-pinned`](docs/rules/action-not-sha-pinned.md) | 信息 | 安全 | 报告未固定到完整提交 SHA 的第三方操作。 |
| [`risky-pull-request-target`](docs/rules/risky-pull-request-target.md) | 警告/错误 | 安全 | 报告 `pull_request_target`，对于高风险模式提供错误。 |
| [`missing-timeout`](docs/rules/missing-timeout.md) | 警告 | 可靠性 | 报告没有 `timeout-minutes` 的任务。 |
| [`missing-concurrency`](docs/rules/missing-concurrency.md) | 信息 | 成本 | 报告可能从 `concurrency` 中受益的工作流程。 |
| [`setup-node-cache-missing`](docs/rules/setup-node-cache-missing.md) | 信息 | 性能 | 报告使用 `actions/setup-node` 而没有依赖缓存的用法。 |
| [`broad-push-trigger`](docs/rules/broad-push-trigger.md) | 信息 | 成本 | 报告在每次推送时运行而没有分支、标签或路径过滤器的工作流程。 |
| [`duplicate-workflow-name`](docs/rules/duplicate-workflow-name.md) | 信息 | 可维护性 | 报告跨文件重复的工作流程名称。 |
| [`yaml-parse-error`](docs/rules/yaml-parse-error.md) | 错误 | 正确性 | 报告无效的工作流程 YAML 而不终止扫描。 |
想要添加下一个规则？规则系统故意很小：一个规则类，专注的测试，一个文档页面，和一个 README 更新。参见 [添加规则](docs/contributing/adding-a-rule.md).
## CLI 参考
```
gh-actions-doctor scan [options]
Options:
--path Workflow directory or file. Defaults to ./.github/workflows.
--format Output format. Defaults to text.
--fail-on
Controls non-zero exit code. Defaults to error.
--include Run only selected rules.
--exclude Skip selected rules.
--strict Promote selected security findings.
--config Config file. Defaults to .gh-actions-doctor.yml if present.
```
## 配置
`gh-actions-doctor` 在存在时自动从当前存储库根目录读取 `.gh-actions-doctor.yml` 或 `.gh-actions-doctor.yaml`。使用 `--config ` 选择文件或使用 `--config none` 禁用配置加载。
```
path: .github/workflows
format: text
failOn: warning
strict: true
exclude:
- action-not-sha-pinned
severity:
missing-permissions: error
```
CLI 提供的值优先于匹配的配置字段。参见 [配置](docs/configuration.md) 获取完整参考。
## JSON 输出
使用 JSON 输出进行自动化：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --format json
```
JSON 有效负载包括：
- 摘要计数，
- 发现文件路径，
- 严重性，
- 规则 ID，
- 类别，
- 消息，
- 建议，
- 当可用时，源行和列。
## GitHub Actions 使用
将 `gh-actions-doctor` 添加到 CI 工作流程以捕捉每个 PR 中的问题：
```
- uses: actions/setup-dotnet@v5
with:
dotnet-version: 10.0.x
- run: dotnet run --project src/GhActionsDoctor.Cli -- scan --fail-on warning
```
有关完整示例，请参阅 [CI 工作流程](.github/workflows/ci.yml)，该工作流程扫描此存储库。
在合并工作流程更改之前，运行 [工作流程加固清单](docs/workflow-hardening-checklist.md) 以进行权限、固定、超时、触发器和机密的简洁审查。
## 开发
恢复、构建和测试：
```
dotnet restore
dotnet build GhActionsDoctor.sln
dotnet test GhActionsDoctor.sln
```
尝试示例工作流程：
```
dotnet run --project src/GhActionsDoctor.Cli -- scan --path samples/good --fail-on none
dotnet run --project src/GhActionsDoctor.Cli -- scan --path samples/bad --fail-on none
```
打包为本地 .NET 工具：
```
dotnet pack src/GhActionsDoctor.Cli --configuration Release
dotnet tool install --tool-path .tmp/tools gh-actions-doctor --version 0.2.0 --add-source src/GhActionsDoctor.Cli/bin/Release
.tmp/tools/gh-actions-doctor scan
```
## 贡献
欢迎贡献。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/contributing/adding-a-rule.md](docs/contributing/adding-a-rule.md) 获取指导。
良好的贡献路径：
- 添加一个专注的工作流程规则，包括测试和文档。
- 改进发现源位置。
- 添加报告输出，如 SARIF 或 GitHub 注释。
- 添加常见项目类型的示例工作流程。
- 改进解析器对真实世界工作流程 YAML 的健壮性。
[良好的入门问题](https://github.com/Wezylnia/gh-actions-doctor/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) | [需要帮助](https://github.com/Wezylnia/gh-actions-doctor/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22)
## 路线图
参见 [docs/roadmap.md](docs/roadmap.md) 获取发布路线图，[docs/project-status.md](docs/project-status.md) 获取当前项目状态，以及 [docs/rules/README.md](docs/rules/README.md) 获取规则目录。
## 存储库治理
公共存储库已设置为小型、可审查的贡献。`main` 受保护，CI 是必需的，`CODEOWNERS` 将审查路由到维护者。为针对 `main` 的拉取请求配置了过时审查驳回、最后推送批准、对话解决、禁用强制推送/删除、管理员紧急绕过和 GitHub Copilot 自动 PR 审查。
## 许可证
MIT。参见 [LICENSE](LICENSE).
标签：GitHub Actions, .NET CLI, 二进制发布, 代码审查, 代码维护, 多人体追踪, 安全可观测性, 安全扫描, 工作流管理, 开源工具, 开源框架, 性能优化, 成本分析, 持续集成, 时序注入, 最佳实践, 检测绕过, 版本控制, 自动笔记