azure-pipelines-validator

Azure Pipelines 验证器

使用此技能，先通过本地脚本验证 Azure DevOps 管道 YAML（azure-pipelines.yml / azure-pipelines.yaml），只有本地输出不足时才查阅文档。

触发语句

用户提出以下请求时，使用此技能：

• “验证我的 azure-pipelines.yml。”
• “这个 Azure 管道 YAML 为什么运行失败？”
• “对这个 Azure DevOps 管道执行安全扫描。”
• “检查这个管道是否存在最佳实践问题。”
• “在合并前，在 CI 中审查这个管道。”

不要使用此技能从头生成管道。请改用 azure-pipelines-generator。

确定性路径设置（避免歧义）

从任意目录运行，并使用显式绝对路径：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
SKILL_DIR="$REPO_ROOT/devops-skills-plugin/skills/azure-pipelines-validator"
PIPELINE_FILE="$REPO_ROOT/azure-pipelines.yml"

如果 REPO_ROOT 为空，请停止并询问仓库根目录路径。不要猜测路径。

验证单个文件：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE"

从当前目录自动检测（最多向下搜索 3 层）：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh"

如果自动检测返回多个文件，请使用一个显式文件路径重新运行。

本地优先执行模式

1. 预检

• 确认 bash 和 python3 可用。
• 确认目标文件存在。

2. 运行本地验证器

• 默认完整检查：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE"

• 仅检查语法：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --syntax-only

• 仅检查最佳实践：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --best-practices

• 仅检查安全性：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --security-only

• 严格模式（警告视为失败）：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --strict

3. 解读退出状态

• 0：通过（或仅有非阻断检查结果）
• 1：验证失败（存在阻断问题）
• 2：调用无效（文件缺失或有歧义，或参数错误）

4. 按照下方的报告格式返回发现结果。

预期报告格式（按严重性分类）

始终使用以下结构返回结果：

Validation Report: <path>

Summary:
- Blocking: <count>        # Syntax errors + Security critical/high
- Warning: <count>         # Security medium/low + best-practice warnings
- Info: <count>            # Suggestions
- Skipped: <count>         # Explicitly name skipped checks

Findings:
- [Blocking][syntax][<rule-id>] line <n> - <message>
- [Blocking][security-high][<rule-id>] line <n> - <message>
- [Warning][security-medium][<rule-id>] line <n> - <message>
- [Warning][best-practice][<rule-id>] line <n> - <message>
- [Info][best-practice][<rule-id>] line <n> - <message>

Remediation:
- <short, concrete fix per finding>

Execution Notes:
- Commands run: <exact commands>
- Environment/fallback notes: <tool missing, skipped checks, offline constraints>

升级策略（仅在需要时查阅文档）

先运行本地检查。仅当符合以下至少一个条件时，才升级处理：

• 本地发现的问题取决于上游当前行为（任务版本、弃用情况、新输入项）。
• 用户询问 Azure Pipelines 任务或架构的“最新/当前/近期”详情。
• 本地脚本无法判断特定任务/资源语法是否有效。

升级顺序：

1. 优先使用 Context7 文档工具。

mcp__context7__resolve-library-id(...)
mcp__context7__query-docs(...)

2. 其次查阅官方文档（learn.microsoft.com / Microsoft Azure DevOps 文档）。
3. 只有前两者不足时才使用常规网络搜索。

升级处理时，请引用来源 URL，并说明本地检查无法回答的问题。

后备处理方式

工具不可用时，使用以下对应方案：

• 条件：yamllint 不可用。

• 操作：继续进行语法、最佳实践和安全性检查。

• 报告说明：“由于 yamllint 不可用，已跳过 YAML lint 检查。”

• 条件：python3 不可用，或虚拟环境/依赖项设置失败。

• 操作：标记脚本验证受阻；仅在用户要求时执行手动 YAML 审查。

• 报告说明：“由于缺少 Python 运行时/依赖项，本地脚本验证受阻。”

• 条件：需要依赖项/文档，但无法联网。

• 操作：运行仍可执行的本地检查；暂缓文档/版本验证。

• 报告说明：“由于处于离线环境，已暂缓外部验证。”

• 条件：自动检测到多个管道文件。

• 操作：不要随意选择；要求用户明确指定目标文件路径。

• 报告说明：“验证已暂停，直至指定单个目标文件。”

规则分类（脚本检查内容）

语法示例：

• yaml-syntax
• yaml-invalid-root
• invalid-hierarchy
• task-invalid-format
• pool-invalid
• deployment-missing-strategy

最佳实践示例：

• missing-displayname
• task-version-zero
• task-missing-version
• pool-latest-image
• missing-cache
• missing-deployment-condition

安全性示例：

• hardcoded-password
• hardcoded-secret
• curl-pipe-shell
• eval-command
• insecure-ssl
• container-latest-tag
• variable-not-secret

在报告中直接使用脚本输出的规则 ID。

参考资料和示例

• 语法参考：docs/azure-pipelines-reference.md
• 管道示例：examples/

快速本地测试：

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$SKILL_DIR/examples/basic-pipeline.yml"

完成标准

满足以下所有条件时，此技能执行即告完成：

• 触发条件明确匹配，并在靠前位置提供了通俗易懂的示例。
• 已使用明确无歧义的路径运行验证命令。
• 报告按严重级别分类（Blocking、Warning、Info、Skipped）。
• 明确报告因工具不可用或环境限制而采取的回退行为。
• 仅在本地检查不足时查阅外部文档。