解决act工具误将非工作流YAML文件识别为工作流的问题

在GitHub Actions生态中，act是一个流行的本地运行GitHub Actions工作流的工具。然而，许多开发者在使用过程中遇到了一个常见问题：act会将.github/workflows目录下的所有YAML文件都尝试解析为工作流文件，即使这些文件实际上是其他用途的配置文件。

问题现象

当项目目录结构如下时：

.github
    └── workflows
        ├── workflow-a.yml
        ├── workflow-b.yml
        ├── workflow-c.yml
        └── scripts
            ├── script-a.sh
            └── script-a.config.yml

其中script-a.config.yml是供script-a.sh使用的配置文件，而非GitHub Actions工作流文件。执行act -l命令时，act会尝试将该配置文件解析为工作流文件，导致如下错误：

Error: workflow is not valid. 'script-a.config.yml': Line: 1 Column 1: Unknown Property test

问题原因

act工具默认会扫描.github/workflows目录及其子目录下的所有YAML文件，并尝试将它们解析为GitHub Actions工作流。这种设计源于GitHub Actions本身的工作机制，但GitHub官方实现中可能已经对此进行了优化。

解决方案

方案一：使用--no-recurse参数

最简单的解决方案是使用--no-recurse参数，这会阻止act递归扫描子目录：

act --no-recurse -l

这个参数告诉act只处理.github/workflows根目录下的YAML文件，而忽略子目录中的文件。值得注意的是，这种行为在未来可能会成为act的默认行为。

方案二：明确指定工作流文件

另一种更精确的方法是使用-W参数直接指定要运行的工作流文件路径：

act -W ./.github/workflows/workflow-a.yml -l

这种方法完全避免了扫描其他文件，直接针对特定工作流文件进行操作，适合在复杂项目中精确控制。

最佳实践建议

1. 合理组织项目结构：考虑将非工作流配置文件放在.github目录的其他子目录中，而非workflows目录下

2. 使用明确的参数：在CI/CD脚本中，尽量使用-W参数明确指定工作流文件，避免歧义

3. 关注版本更新：随着GitHub Actions的更新，未来版本的act可能会默认不递归扫描子目录

4. 文档记录：在项目文档中记录这些特殊配置，方便团队成员理解和使用

通过以上方法，开发者可以有效地解决act工具误解析非工作流YAML文件的问题，确保本地测试流程顺畅无阻。