验证、调试和修复 GitHub Actions 工作流时…

适用于需要校验 .github/workflows/*.yml、自定义 action 或公共 action 的语法、依赖、安全、版本和本地可执行性的场景。

适用场景

解决思路

1. 设置技能路径：`SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"`，每次 shell 会话设置一次。
2. 安装工具：运行 `bash "$SKILL_DIR/scripts/install_tools.sh"`，把 act（本地工作流执行）和 actionlint（静态分析）安装到 `scripts/.tools/`。
3. 从包含 `.github/workflows/` 的仓库根目录运行验证脚本：`bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>`。
4. 对每个 actionlint/act 错误，查询错误类型到参考文件的映射表，然后提取匹配的修复模式。
5. 应用最小引用策略：包含工具输出中的精确错误行；只从 `references/` 引用最小的有用片段（优先 <=8 行）；其余内容改写并引用来源文件/章节；展示修正后的工作流代码。
6. 处理未映射错误：标记为 `UNMAPPED`；捕获精确工具输出、工作流文件和行号（如果有）；先查 `references/common_errors.md` 的通用章节；仍未解决则用精确错误字符串搜索官方文档；在修复后重跑通过前把修复标记为 `provisional`。
7. 验证公共 action 版本：对每个 `uses: owner/action@version`，检查 `references/action_versions.md`；对未知 action 对照官方文档验证；确认必需输入和弃用情况。离线模式：若网络/文档查询不可用，只依赖 `references/action_versions.md`；把未知 action 标记为 `UNVERIFIED-OFFLINE`；没有在线验证就不要声称 `latest` 版本。
8. 应用修复后必须重跑验证：`bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>`。
9. 提供最终总结：包含发现的问题和应用的修复；任何 `UNMAPPED` 或 `UNVERIFIED-OFFLINE` 项；修复后重跑命令和结果；剩余警告/风险说明。
10. 静态分析：先运行 `bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/ci.yml`。actionlint 检查 YAML 语法、schema 合规、表达式语法、runner 标签、action 输入/输出、job 依赖、CRON 语法、glob 模式、shell 脚本和安全漏洞。
11. 本地测试：静态分析通过后，运行 `bash "$SKILL_DIR/scripts/validate_workflow.sh" --test-only .github/workflows/` 用 act 测试工作流执行；act 有局限性，见 `references/act_usage.md`。
12. 完整验证：运行 `bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml`。默认行为：如果 `act` 缺失，完整验证回退到仅 actionlint；如果 Docker 不可用，跳过 act 并继续 actionlint；`--check-versions` 在离线/本地模式使用 `references/action_versions.md`。
13. 验证工作流：单工作流用 `bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml`；所有工作流用 `bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/`。关键验证点包括触发器、job 配置、runner 标签、环境变量、secrets、条件、matrix 策略。
14. 验证自定义本地 action：创建使用该自定义 action 的测试工作流，然后运行 `bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/test-custom-action.yml`。
15. 验证公共 action：先查 `references/action_versions.md`；对未知 action 用官方文档或网络搜索；验证必需输入和版本；检查弃用警告；运行验证脚本。离线时把未知版本标记为 `UNVERIFIED-OFFLINE`，避免声称 `latest/current`。搜索格式：`"[action-name] [version] github action documentation"`。
16. 强制参考咨询：当 actionlint 报告任何已映射错误时，查 `references/common_errors.md`，找到匹配错误并应用最小引用策略；当 actionlint 报告未映射错误时，查 `references/common_errors.md` 加官方文档，标记 `UNMAPPED`，捕获精确输出并通过重跑验证；当 act 因 Docker/运行时错误失败时，查 `references/act_usage.md` 的 Troubleshooting；当 act 失败但工作流在 GitHub 上正常时，查 `references/act_usage.md` 的 Limitations；当用户询问 actionlint 配置时，查 `references/actionlint_usage.md` 并提供示例；当用户询问 act 选项时，查 `references/act_usage.md` 的 Advanced Options；当检测到安全漏洞时，查 `references/common_errors.md` 并引用最小安全修复片段；当验证 action 版本时，查 `references/action_versions.md` 的版本表和离线说明；当使用现代功能时，查 `references/modern_features.md` 的语法示例；当有 runner 问题/错误时，查 `references/runners.md` 的标签和可用性。
17. 按脚本输出模式查参考文件：`[syntax-check]`、解析、YAML 错误 -> `common_errors.md` 的 Syntax Errors；`[expression]`、`${{`、条件解析 -> `common_errors.md` 的 Expression Errors；`[action]`、`uses:`、输入/输出不匹配 -> `common_errors.md` 的 Action Errors；`[events]` 带 CRON/schedule 文本 -> `common_errors.md` 的 Schedule Errors；`potentially untrusted`、注入警告 -> `common_errors.md` 的 Security 章节；`[runner-label]` 或未知 `runs-on` 标签 -> `runners.md`；`[job-needs]` 依赖错误 -> `common_errors.md` 的 Job Configuration Errors；`[glob]`、`paths`、模式错误 -> `common_errors.md` 的 Path Filter Errors；来自 act 的 Docker/pull/image 错误 -> `act_usage.md` 的 Troubleshooting；无模式匹配 -> `common_errors.md` 加官方文档（标记 `UNMAPPED`）。
18. 按错误模式映射参考文件：`runs-on:`、`runner`、`ubuntu`、`macos`、`windows` -> `references/runners.md` 的 Runner labels；`cron`、`schedule` -> `references/common_errors.md` 的 Schedule Errors；`${{`、`expression`、`if:` -> `references/common_errors.md` 的 Expression Errors；`needs:`、`job`、`dependency` -> `references/common_errors.md` 的 Job Configuration Errors；`uses:`、`action`、`input` -> `references/common_errors.md` 的 Action Errors；`untrusted`、`injection`、`security` -> `references/common_errors.md` 的 Script Injection 章节；`syntax`、`yaml`、`unexpected` -> `references/common_errors.md` 的 Syntax Errors；`docker`、`container` -> `references/act_usage.md` 的 Troubleshooting；`@v3`、`@v4`、`deprecated`、`outdated` -> `references/action_versions.md` 的 Version table；`workflow_call`、`reusable`、`oidc` -> `references/modern_features.md` 的相关章节；`glob`、`path`、`paths:`、`pattern` -> `references/common_errors.md` 的 Path Filter Errors。
19. 参考文件摘要：`references/act_usage.md` 含 act 工具用法、命令、选项、限制、故障排除；`references/actionlint_usage.md` 含 actionlint 验证类别、配置、集成；`references/common_errors.md` 含常见错误目录和修复；`references/action_versions.md` 含当前 action 版本、弃用时间线、SHA pinning；`references/modern_features.md` 含可复用工作流、SBOM、OIDC、environments、containers；`references/runners.md` 含 GitHub 托管 runner（ARM64、GPU、M2 Pro、弃用）。
20. 故障排除：工具未找到 -> 运行 `bash "$SKILL_DIR/scripts/install_tools.sh"`；Docker daemon 未运行 -> 启动 Docker 或使用 `--lint-only`；权限拒绝 -> 运行 `chmod +x "$SKILL_DIR"/scripts/*.sh`；act 失败但 GitHub 正常 -> 见 `references/act_usage.md` 的 Limitations。
21. 调试模式：`actionlint -verbose .github/workflows/ci.yml` 查看详细 actionlint 输出；`act -v` 查看详细 act 输出；`act -n` 做 dry-run（不执行）。
22. 最佳实践：总是先在本地验证；在 CI/CD 中使用 actionlint 自动化验证；固定 action 版本（使用 `@v6` 而非 `@main` 以保证稳定性，安全场景用 SHA pinning）；保持工具更新，定期更新 actionlint 和 act；未知 action 使用官方文档验证用法和版本；检查版本兼容性，见 `references/action_versions.md`；启用 shellcheck 以尽早捕获 shell 脚本问题；审查安全警告，处理脚本注入问题。
23. 限制：act 不能本地运行所有 GitHub Actions 功能；act 需要 Docker 运行；网络 action 可能本地失败；私有 action 无法在没有访问权限时验证；静态分析不能捕获所有运行时问题；act 只能验证 `.github/workflows/` 目录中的工作流，外部文件（如 `examples/`）只能用 actionlint 验证。
24. 快速示例：预提交验证：设置 `SKILL_DIR`，运行 `bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/`，然后 `git add .github/workflows/ && git commit -m "Update workflows"`。调试失败工作流：运行 `bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/failing.yml`，修复问题，再运行 `bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/failing.yml`。
25. 完整多错误处理流程：运行验证 `bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only workflow.yml`；对每个错误查阅参考并引用修复；提供修正后的工作流；强制重跑 `bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only workflow.yml`；总结每个错误类型、修复和剩余建议。
26. 完成标准：触发匹配且选择正确验证模式；每个映射错误包含来源引用和最小引用；每个未映射错误标记 `UNMAPPED` 并捕获精确输出；公共 action 版本已验证或标记 `UNVERIFIED-OFFLINE`；执行修复后重跑并报告结果。
27. 总结流程：Setup（用 `install_tools.sh` 安装工具）；Validate（对工作流文件运行 `validate_workflow.sh`）；Fix（用参考文档处理问题）；Rerun（修复后必须重跑验证）；Search（用官方文档验证未知 action）；Commit（提交已验证的工作流）。
28. 处理错误示例：对 `runs-on: ubuntu-lastest`，脚本输出 `label "ubuntu-lastest" is unknown`；查阅 `references/runners.md` 或 `references/common_errors.md` 的 Invalid Runner Label；引用修复：坏例 `runs-on: ubuntu-lastest`，好例 `runs-on: ubuntu-latest`；有效 runner 标签包括 `ubuntu-latest`、`ubuntu-24.04`、`ubuntu-22.04`、`windows-latest`、`windows-2025`、`windows-2022`、`macos-latest`、`macos-15`、`macos-14`；提供修正后的代码。

适用边界 · 注意事项

• 当工作流依赖 GitHub 专有功能、网络 API 或私有 action 时，act 本地测试可能失败或不适用。
• 没有运行中的 Docker 时，不能使用 act 做本地执行测试，只能进行 actionlint 静态分析。
• 对 `.github/workflows/` 目录之外的文件，act 无法验证，只能用 actionlint 验证。