GitHubActions验证器 github-actions-validator

GitHub Actions Validator

概述

使用行业标准工具（actionlint 和 act）验证和测试 GitHub Actions 工作流、自定义操作和公共操作。这项技能提供全面的验证，包括语法检查、静态分析、本地工作流执行测试和具有版本感知的文档查找的动作验证。

何时使用这项技能

当：

• 验证工作流文件：检查 .github/workflows/*.yml 的语法错误和最佳实践
• 本地测试工作流：在推送到 GitHub 之前使用 act 运行工作流
• 调试工作流失败：识别工作流配置中的问题
• 验证自定义操作：检查复合、Docker 或 JavaScript 操作
• 验证公共操作：验证来自 GitHub Marketplace 的操作的使用
• 预提交验证：确保在提交之前工作流是有效的

CRITICAL: 助手工作流（必须遵循）

每次验证都必须遵循以下步骤。跳过任何步骤都是不符合规定的。

第 1 步：运行验证脚本

cd .claude/skills/github-actions-validator
bash scripts/validate_workflow.sh <workflow-file-or-directory>

第 2 步：对于每个错误 - 参考参考文件

当 actionlint 或 act 报告任何错误时，您必须：

1. 阅读适当的参考文件（见下面的映射）
2. 找到匹配的错误模式
3. 提取修复/解决方案

第 3 步：向用户引用修复

对于每个错误，提供：

1. 错误消息（来自脚本输出）
2. 解释（来自参考文件）
3. 修复代码（引用自参考文件）
4. 修正后的代码（应用于用户的工作流）

第 4 步：验证公共操作（如果存在）

对于任何公共操作（例如 uses: owner/action@version）：

1. 首先检查 references/action_versions.md 以了解已知操作和版本
2. 使用网络搜索 以查找未知操作："[action-name] [version] github action documentation"
3. 验证所需的输入是否匹配
4. 检查弃用警告

第 5 步：提供完整的摘要

在解决所有错误之后：

• 列出所有应用的修复
• 注意任何警告
• 从 references/ 推荐最佳实践

错误类型到参考文件映射

输出中的错误模式	要阅读的参考文件	引用部分
runs-on:, runner, ubuntu, macos, windows	references/runners.md	运行器标签
cron, schedule	references/common_errors.md	计划错误
${{, expression, if:	references/common_errors.md	表达式错误
needs:, job, dependency	references/common_errors.md	作业配置错误
uses:, action, input	references/common_errors.md	动作错误
untrusted, injection, security	references/common_errors.md	脚本注入部分
syntax, yaml, unexpected	references/common_errors.md	语法错误
docker, container	references/act_usage.md	故障排除
@v3, @v4, deprecated, outdated	references/action_versions.md	版本表
workflow_call, reusable, oidc	references/modern_features.md	相关部分
glob, path, paths:, pattern	references/common_errors.md	路径过滤器错误

示例：完整的错误处理工作流

用户的工作流有这个错误：

runs-on: ubuntu-lastest

第 1 步 - 脚本输出：

label "ubuntu-lastest" is unknown

第 2 步 - 阅读 references/runners.md 或 references/common_errors.md： 找到 “Invalid Runner Label” 部分。

第 3 步 - 向用户引用修复：

错误： label "ubuntu-lastest" is unknown

原因： 运行器标签中的拼写错误（来自 references/common_errors.md）：

# 坏
runs-on: ubuntu-lastest  # 拼写错误

修复（来自 references/common_errors.md）：

# 好
runs-on: ubuntu-latest

有效的运行器标签（来自 references/runners.md）：

• ubuntu-latest, ubuntu-24.04, ubuntu-22.04
• windows-latest, windows-2025, windows-2022
• macos-latest, macos-15, macos-14

第 4 步 - 提供修正后的代码：

runs-on: ubuntu-latest

快速开始

初始设置

cd .claude/skills/github-actions-validator
bash scripts/install_tools.sh

这将安装 act（本地工作流执行）和 actionlint（静态分析）到 scripts/.tools/。

基本验证

# 验证单个工作流
bash scripts/validate_workflow.sh .github/workflows/ci.yml

# 验证所有工作流
bash scripts/validate_workflow.sh .github/workflows/

# 仅 lint（最快）
bash scripts/validate_workflow.sh --lint-only .github/workflows/ci.yml

# 仅测试使用 act（需要 Docker）
bash scripts/validate_workflow.sh --test-only .github/workflows/

核心验证工作流

1. 使用 actionlint 进行静态分析

从静态分析开始，以捕获语法错误和常见问题：

bash scripts/validate_workflow.sh --lint-only .github/workflows/ci.yml

actionlint 检查的内容： YAML 语法、模式合规性、表达式语法、运行器标签、动作输入/输出、作业依赖关系、CRON 语法、全局模式、shell 脚本、安全漏洞。

2. 使用 act 进行本地测试

在通过静态分析后，测试工作流执行：

bash scripts/validate_workflow.sh --test-only .github/workflows/

注意： act 有限制 - 见 references/act_usage.md。

3. 完整验证

bash scripts/validate_workflow.sh .github/workflows/ci.yml

验证资源类型

工作流

# 单个工作流
bash scripts/validate_workflow.sh .github/workflows/ci.yml

# 所有工作流
bash scripts/validate_workflow.sh .github/workflows/

关键验证点： 触发器、作业配置、运行器标签、环境变量、机密、条件、矩阵策略。

自定义本地操作

创建一个测试工作流，该工作流使用自定义操作，然后进行验证：

bash scripts/validate_workflow.sh .github/workflows/test-custom-action.yml

公共操作

当工作流使用公共操作（例如 actions/checkout@v6）时：

1. 使用网络搜索查找操作文档
2. 验证所需的输入和版本
3. 检查弃用警告
4. 运行验证脚本

搜索格式： "[action-name] [version] github action documentation"

参考文件咨询指南

强制性参考咨询

情况	参考文件	操作
actionlint 报告任何错误	references/common_errors.md	查找匹配的错误，引用解决方案
act 出现 Docker 错误	references/act_usage.md	检查故障排除部分
act 失败但工作流在 GitHub 上工作	references/act_usage.md	阅读限制部分
用户询问关于 actionlint 配置	references/actionlint_usage.md	提供示例
用户询问关于 act 选项	references/act_usage.md	阅读高级选项
检测到安全漏洞	references/common_errors.md	引用修复
验证操作版本	references/action_versions.md	检查版本表
使用现代功能	references/modern_features.md	检查语法示例
运行器问题/错误	references/runners.md	检查标签和可用性

脚本输出到参考映射

输出类别	参考文件
[SYNTAX]	common_errors.md - 语法错误
[EXPRESSION]	common_errors.md - 表达式错误
[ACTION]	common_errors.md - 动作错误
[SCHEDULE]	common_errors.md - 计划错误
[SECURITY]	common_errors.md - 安全部分
[DOCKER]	act_usage.md - 故障排除
[ACT-LIMIT]	act_usage.md - 限制

参考文件摘要

文件	内容
references/act_usage.md	Act 工具使用、命令、选项、限制、故障排除
references/actionlint_usage.md	Actionlint 验证类别、配置、集成
references/common_errors.md	常见错误目录及修复
references/action_versions.md	当前操作版本、弃用时间表、SHA 固定
references/modern_features.md	可重用工作流、SBOM、OIDC、环境、容器
references/runners.md	GitHub 托管运行器（ARM64、GPU、M2 Pro、弃用）

故障排除

问题	解决方案
“工具未找到”	运行 bash scripts/install_tools.sh
“Docker 守护进程未运行”	启动 Docker 或使用 --lint-only
“权限被拒绝”	运行 chmod +x scripts/*.sh
act 失败但 GitHub 工作	见 references/act_usage.md 限制

调试模式

actionlint -verbose .github/workflows/ci.yml  # 详细 actionlint
act -v                                         # 详细 act
act -n                                         # 干运行（不执行）

最佳实践

1. 始终先在本地验证 - 在推送之前捕获错误
2. 在 CI/CD 中使用 actionlint - 在管道中自动验证
3. 固定操作版本 - 使用 @v6 而不是 @main 以确保稳定性；SHA 固定以确保安全性
4. 保持工具更新 - 定期更新 actionlint 和 act
5. 使用网络搜索未知操作 - 使用文档验证使用情况
6. 检查版本兼容性 - 见 references/action_versions.md
7. 启用 shellcheck - 及早捕获 shell 脚本问题
8. 审查安全警告 - 解决脚本注入问题

限制

• act 限制：并非所有 GitHub Actions 功能在本地工作
• Docker 要求：act 需要 Docker 运行
• 网络操作：一些 GitHub API 操作可能在本地失败
• 私有操作：无法在没有访问权限的情况下验证
• 运行时行为：静态分析无法捕获所有问题
• 文件位置：act 只能验证 .github/workflows/ 目录中的工作流；外部文件（如 examples/）只能使用 actionlint 验证

快速示例

示例 1：预提交验证

cd .claude/skills/github-actions-validator
bash scripts/validate_workflow.sh .github/workflows/
git add .github/workflows/ && git commit -m "Update workflows"

示例 2：调试失败的工作流

bash scripts/validate_workflow.sh --lint-only .github/workflows/failing.yml
# 修复问题
bash scripts/validate_workflow.sh .github/workflows/failing.yml

完整工作示例：多错误工作流

这个示例演示了 完整的助手工作流 用于处理多个错误。

用户的问题工作流

name: Broken CI
on:
  schedule:
    - cron: '0 0 * * 8'  # ERROR 1
jobs:
  build:
    runs-on: ubuntu-lastest  # ERROR 2
    steps:
      - uses: actions/checkout@v3  # ERROR 3 (outdated)
      - run: echo ${{ github.event.issue.title }}  # ERROR 4 (security)
  deploy:
    needs: biuld  # ERROR 5 (typo)
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

第 1 步：运行验证

bash scripts/validate_workflow.sh --lint-only workflow.yml

输出：

[ERROR] invalid CRON format "0 0 * * 8"
[ERROR] label "ubuntu-lastest" is unknown
[WARN] "github.event.issue.title" is potentially untrusted
[ERROR] job "deploy" needs job "biuld" which does not exist

第 2-3 步：参考参考并引用修复

---

错误 1：无效 CRON 表达式

来自 references/common_errors.md - 计划错误：

原因： 一周中的第 8 天不存在（有效：0-6，其中 0 = 星期日）

# 坏
schedule:
  - cron: '0 0 * * 8'  # 第 8 天不存在

# 好
schedule:
  - cron: '0 0 * * 0'  # 星期日

CRON 格式： minute hour day month weekday

• 工作日：0-6（0 = 星期日）

修复： 将 8 更改为 0（星期日）或 1-6 表示星期一至星期六。

---

错误 2：无效运行器标签

来自 references/common_errors.md - 作业配置错误和 references/runners.md：

原因： 运行器标签中的拼写错误

# 坏
runs-on: ubuntu-lastest  # 拼写错误

# 好
runs-on: ubuntu-latest

有效的标签（来自 references/runners.md）：

• ubuntu-latest（Ubuntu 24.04）
• ubuntu-24.04, ubuntu-22.04
• macos-latest（macOS 15）
• windows-latest（Windows Server 2022）

修复： 将 ubuntu-lastest 更改为 ubuntu-latest。

---

错误 3：过时的操作版本

来自 references/action_versions.md：

操作	当前版本	最低支持
actions/checkout	v6	v4

SHA 固定最佳实践：

# 推荐：SHA 固定与版本注释
- uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0

修复： 从 @v3 更新到 @v6（或 SHA 固定版本）。

---

错误 4：安全漏洞（脚本注入）

来自 references/common_errors.md - 表达式错误：

警告： 通过不受信任的输入可能发生脚本注入

# 坏 - 容易受到注入攻击
run: echo ${{ github.event.issue.title }}

# 好 - 使用环境变量
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"

为什么： 不受信任的输入（问题标题、PR 正文、提交消息）可能包含恶意命令。使用环境变量可以对输入进行清理。

修复： 通过环境变量传递不受信任的输入。

---

错误 5：未定义的作业依赖关系

来自 references/common_errors.md - 作业配置错误：

错误： 作业 ‘deploy’ 依赖于不存在的作业 ‘biuld’

# 坏
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: biuld  # 拼写错误

# 好
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: build

修复： 将 biuld 更改为 build。

---

第 4 步：提供修正后的工作流

name: Fixed CI
on:
  schedule:
    - cron: '0 0 * * 0'  # 已修复：星期日（0-6 有效）
jobs:
  build:
    runs-on: ubuntu-latest  # 已修复：拼写错误已更正
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0 - 已修复：更新版本
      - name: Process issue
        env:
          TITLE: ${{ github.event.issue.title }}  # 已修复：使用环境变量
        run: echo "$TITLE"
  deploy:
    needs: build  # 已修复：拼写错误已更正
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

第 5 步：摘要

错误	类型	应用的修复
CRON 0 0 * * 8	计划	更改为 0 0 * * 0
ubuntu-lastest	运行器	更改为 ubuntu-latest
checkout@v3	过时操作	更新为 @v6.0.0（SHA 固定）
直接 ${{ }} 在运行中	安全	包装在环境变量中
needs: biuld	作业依赖关系	更改为 needs: build

建议：

• 定期运行 bash scripts/validate_workflow.sh --check-versions
• 在生产工作流中为所有操作使用 SHA 固定
• 始终通过环境变量传递不受信任的输入

摘要

1. 设置：使用 install_tools.sh 安装工具
2. 验证：在工作流文件上运行 validate_workflow.sh
3. 修复：使用参考文档解决问题
4. 测试：使用 act 在本地进行验证（如果可能）
5. 搜索：使用网络搜索验证未知操作
6. 提交：自信地推送经过验证的工作流

如需详细信息，请参考 references/ 中的适当参考文件。