github-actions-validator

GitHub Actions 验证器

概述

使用行业标准工具（actionlint 和 act）验证和测试 GitHub Actions 工作流、自定义操作和公开操作。此技能提供全面验证，包括语法检查、静态分析、本地工作流执行测试，以及结合版本文档查询的操作验证。

触发短语

当请求包含以下短语时，使用此技能：

• “验证此 GitHub Actions 工作流”
• “检查我的 .github/workflows/*.yml 文件”
• “调试 actionlint 错误”
• “使用 act 在本地测试此工作流”
• “验证 GitHub Action 版本或弃用情况”

何时使用此技能

在以下情况下使用此技能：

• 验证工作流文件：检查 .github/workflows/*.yml 中的语法错误和最佳实践
• 在本地测试工作流：将工作流推送到 GitHub 前，使用 act 运行
• 调试工作流故障：找出工作流配置中的问题
• 验证自定义操作：检查复合操作、Docker 操作或 JavaScript 操作
• 验证公开操作：验证对 GitHub Marketplace 中操作的使用
• 提交前验证：确保工作流在提交前有效

必需的执行流程

每次验证都应按顺序遵循以下步骤。

步骤 1：设置技能路径并运行验证

在包含 .github/workflows/ 的仓库根目录中运行命令。

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>

步骤 2：将每个错误对应到参考资料

对于每个 actionlint/act 错误，查阅下方的映射表，然后提取匹配的修复模式。

步骤 3：遵循最少引用原则

对于每个问题：

1. 提供工具输出中的确切错误行。
2. 仅引用 references/ 中最精简且有用的片段（最好不超过 8 行）。
3. 转述其余内容，并注明来源文件和章节。
4. 展示修正后的工作流代码。

步骤 4：明确处理未映射的错误

如果错误与任何映射都不匹配：

1. 将其标记为 UNMAPPED。
2. 记录确切的工具输出、工作流文件和行号（如有）。
3. 首先检查 references/common_errors.md 的通用章节。
4. 如果仍未解决，使用完整错误字符串搜索官方文档。
5. 在修复后重新运行验证并通过之前，将修复标记为 provisional。

步骤 5：验证公开操作的版本

对于每个 uses: owner/action@version：

1. 检查 references/action_versions.md。
2. 对于未知操作，依据官方文档进行验证。
3. 确认所需输入和弃用情况。

离线模式行为：

• 如果无法联网或查询文档，仅依赖 references/action_versions.md。
• 将未知操作标记为 UNVERIFIED-OFFLINE。
• 未经过在线验证，不要声称某个版本是“最新”版本。

步骤 6：必须在修复后重新运行

应用修复后，在最终确认前重新运行验证：

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>

步骤 7：提供最终摘要

最终输出应包括：

• 发现的问题和已应用的修复
• 所有 UNMAPPED 或 UNVERIFIED-OFFLINE 项
• 修复后重新运行的命令和结果
• 剩余的警告和风险说明

错误类型与参考文件映射

输出中的错误模式	要读取的参考文件	要引用的章节
runs-on:, runner, ubuntu, macos, windows	references/runners.md	Runner 标签
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	版本表
workflow_call, reusable, oidc	references/modern_features.md	相关章节
glob, path, paths:, pattern	references/common_errors.md	Path Filter Errors

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

用户的工作流出现此错误：

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

原因： Runner 标签中有拼写错误（来自 references/common_errors.md）：

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

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

# 正确
runs-on: ubuntu-latest

有效的 Runner 标签（来自 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

快速入门

每个 Shell 会话设置一次：

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"

初始设置

bash "$SKILL_DIR/scripts/install_tools.sh"

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

基本验证

# Validate a single workflow
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

# Validate all workflows
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/

# Lint-only (fastest)
bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/ci.yml

# Test-only with act (requires Docker)
bash "$SKILL_DIR/scripts/validate_workflow.sh" --test-only .github/workflows/

核心验证工作流

1. 使用 actionlint 进行静态分析

先进行静态分析，以捕获语法错误和常见问题：

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

actionlint 检查内容： YAML 语法、架构合规性、表达式语法、Runner 标签、操作的输入/输出、作业依赖关系、CRON 语法、glob 模式、Shell 脚本、安全漏洞。

2. 使用 act 进行本地测试

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

bash "$SKILL_DIR/scripts/validate_workflow.sh" --test-only .github/workflows/

注意： act 有一些限制——请参阅 references/act_usage.md。

3. 完整验证

bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

工具或运行环境不可用时的默认行为：

• 如果缺少 act，完整验证将回退为仅运行 actionlint。
• 如果 Docker 不可用，完整验证将跳过 act，继续运行 actionlint。
• --check-versions 可在离线/本地模式下使用 references/action_versions.md。

验证资源类型

工作流

# Single workflow
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

# All workflows
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/

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

自定义本地操作

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

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

公共操作

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

1. 首先检查 references/action_versions.md
2. 对于未知操作，使用官方文档（或网页搜索）
3. 验证必需的输入和版本
4. 检查是否有弃用警告
5. 运行验证脚本

如果处于离线状态：

• 将未知版本标记为 UNVERIFIED-OFFLINE
• 在线验证尚不可行时，避免声称其为“最新/当前”版本

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

参考文件查阅指南

必须查阅参考资料

情况	参考文件	操作
actionlint 报告了任何已映射的错误	references/common_errors.md	查找匹配的错误，并采用最简引用策略
actionlint 报告了未映射的错误	references/common_errors.md + 官方文档	标记为 UNMAPPED，记录准确输出并通过重新运行验证
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	引用最简安全修复代码片段
验证 action 版本	references/action_versions.md	查看版本表和离线说明
使用现代功能	references/modern_features.md	查看语法示例
运行器相关问题／错误	references/runners.md	查看标签和可用性

脚本输出与参考资料的映射

输出模式	参考文件
[syntax-check]、解析、YAML 错误	common_errors.md - 语法错误
[expression]、${{、条件解析	common_errors.md - 表达式错误
[action]、uses:、输入／输出不匹配	common_errors.md - Action 错误
[events] 中包含 CRON／schedule 文本	common_errors.md - 计划任务错误
potentially untrusted、注入警告	common_errors.md - 安全部分
[runner-label] 或未知的 runs-on 标签	runners.md
[job-needs] 依赖错误	common_errors.md - 作业配置错误
[glob]、paths、模式错误	common_errors.md - 路径筛选器错误
act 报告 Docker／拉取／镜像错误	act_usage.md - 故障排除
不匹配任何模式	common_errors.md + 官方文档（标记为 UNMAPPED）

参考文件摘要

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

故障排除

问题	解决方案
"Tools not found"	运行 bash "$SKILL_DIR/scripts/install_tools.sh"
"Docker daemon not running"	启动 Docker 或使用 --lint-only
"Permission denied"	运行 chmod +x "$SKILL_DIR"/scripts/*.sh
act 运行失败，但 GitHub 上正常	查看 references/act_usage.md 中的限制部分

调试模式

actionlint -verbose .github/workflows/ci.yml  # Verbose actionlint
act -v                                         # Verbose act
act -n                                         # Dry-run (no execution)

最佳实践

1. 始终先在本地验证 - 在推送前发现错误
2. 在 CI/CD 中使用 actionlint - 在流水线中自动执行验证
3. 固定 action 版本 - 为确保稳定性使用 @v6 而不是 @main；为确保安全性固定 SHA
4. 保持工具更新 - 定期更新 actionlint 和 act
5. 遇到未知 action 时查阅官方文档 - 验证用法和版本
6. 检查版本兼容性 - 查看 references/action_versions.md
7. 启用 shellcheck - 尽早发现 shell 脚本问题
8. 检查安全警告 - 处理脚本注入问题

局限性

• act 的局限性：并非所有 GitHub Actions 功能都能在本地运行
• Docker 要求：act 要求 Docker 正在运行
• 网络操作：某些 GitHub API 操作可能在本地失败
• 私有操作：没有访问权限时无法验证
• 运行时行为：静态分析无法发现所有问题
• 文件位置：act 只能验证 .github/workflows/ 目录中的工作流；目录外的文件（如 examples/ 中的文件）只能通过 actionlint 验证

快速示例

示例 1：提交前验证

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/
git add .github/workflows/ && git commit -m "Update workflows"

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

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/failing.yml
# Fix issues
bash "$SKILL_DIR/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 "$SKILL_DIR/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：无效的 Runner 标签

摘自 references/common_errors.md — 作业配置错误和 references/runners.md：

**原因：**Runner 标签中有拼写错误

# 错误
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'  # Fixed: Sunday (0-6 valid)
jobs:
  build:
    runs-on: ubuntu-latest  # Fixed: typo corrected
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0 - Fixed: updated version
      - name: Process issue
        env:
          TITLE: ${{ github.event.issue.title }}  # Fixed: use env var
        run: echo "$TITLE"
  deploy:
    needs: build  # Fixed: typo corrected
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

步骤 5：必须重新运行

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only workflow.yml

预期的重新运行结果：

• 不再出现之前的错误
• 如有剩余警告，应明确记录

步骤 6：总结

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

建议：

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

完成标准

满足以下所有条件即表示验证工作已完成：

• 触发条件已匹配，并选择了正确的验证模式。
• 每个已映射的错误都包含源引用和最短引文。
• 每个未映射的错误都标记为 UNMAPPED，并捕获了完整输出。
• 已验证公开的 Action 版本，或将其标记为 UNVERIFIED-OFFLINE。
• 已执行修复后的重新运行，并报告结果。

总结

1. 设置：使用 install_tools.sh 安装工具
2. 验证：对工作流文件运行 validate_workflow.sh
3. 修复：参考文档解决问题
4. 重新运行：通过强制执行的修复后验证运行来确认修复
5. 搜索：使用官方文档验证未知 Action
6. 提交：放心推送已验证的工作流

如需详细信息，请查阅 references/ 中相应的参考文件。