jenkinsfile-validator

Jenkinsfile 验证器技能

使用此技能验证 Jenkins 流水线和共享库：先运行本地脚本，然后可选择结合插件文档补充分析结果。

触发短语

请求内容符合以下情形时使用此技能：

• “验证这个 Jenkinsfile”
• “检查这个流水线是否存在安全问题”
• “检查我的声明式／脚本式流水线”
• “为什么这个 Jenkins 流水线未通过语法检查？”
• “验证 vars/.groovy 或 src/**/.groovy 共享库文件”

范围

此技能可验证：

• 声明式流水线（pipeline { ... }）
• 脚本式流水线（node { ... } 和 Groovy 风格流水线）
• 共享库文件（vars/*.groovy、src/**/*.groovy）
• 硬编码凭据模式
• 流水线最佳实践和可维护性指标

前置条件

除非另有说明，请在仓库根目录运行命令。

必需工具

• bash
• grep
• sed
• awk
• head
• wc
• find（扫描共享库目录时需要）

推荐工具

• jq（可选；可改进涉及大量 JSON 的故障排查工作流）

脚本前置条件

• 脚本位于 devops-skills-plugin/skills/jenkinsfile-validator/scripts/
• 即使子脚本缺少 +x，主编排器也能运行它们（会回退到 bash）
• 如果要直接执行（./script.sh），请将脚本设为可执行：

chmod +x devops-skills-plugin/skills/jenkinsfile-validator/scripts/*.sh

运行前检查（推荐）

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"

command -v bash grep sed awk head wc find >/dev/null && echo "required tools: ok" || echo "required tools: missing"
command -v jq >/dev/null && echo "jq: installed (optional)" || echo "jq: missing (optional)"

[ -d "$SKILL_DIR/scripts" ] && echo "scripts dir: ok" || echo "scripts dir: missing"
[ -f "$SKILL_DIR/scripts/validate_jenkinsfile.sh" ] && echo "main validator: ok" || echo "main validator: missing"

快速开始（标准化路径）

使用单个基础路径变量，避免路径歧义。

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
TARGET_JENKINSFILE="Jenkinsfile"

# Full validation (recommended)
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" "$TARGET_JENKINSFILE"

常用选项

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
TARGET_JENKINSFILE="Jenkinsfile"

bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --syntax-only "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --security-only "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --best-practices "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --no-security "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --no-best-practices "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --strict "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --assume-declarative "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --assume-scripted "$TARGET_JENKINSFILE"

共享库验证

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"

bash "$SKILL_DIR/scripts/validate_shared_library.sh" vars/myStep.groovy
bash "$SKILL_DIR/scripts/validate_shared_library.sh" vars/
bash "$SKILL_DIR/scripts/validate_shared_library.sh" src/
bash "$SKILL_DIR/scripts/validate_shared_library.sh" /path/to/shared-library

回归和本地 CI 检查

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
bash "$SKILL_DIR/tests/run_local_ci.sh"

run_local_ci.sh 是回归覆盖的受支持本地／CI 入口。它会运行：

• 对所有 scripts/*.sh 和 tests/*.sh 文件执行 bash -n 语法检查
• tests/test_validate_jenkinsfile.sh 回归场景

确定性验证流程

1）检测流水线类型

• pipeline { => 声明式验证器
• node (...) 或 node { => 脚本式验证器
• 未知 => 默认采取失败关闭策略（ERROR [TypeDetection]）
• 对类型不明确的文件，可使用 --assume-declarative 或 --assume-scripted 覆盖

2）运行语法验证

• 声明式：validate_declarative.sh
• 脚本式：validate_scripted.sh

3）运行安全扫描

• common_validation.sh check_credentials

4）运行最佳实践检查

• best_practices.sh

5）汇总并返回最终状态

• 统一摘要，列出各阶段的通过／失败情况和最终退出代码

6）修改脚本后运行回归测试套件

• bash tests/run_local_ci.sh
• 用于本地提交前检查和 CI 作业配置

单独运行脚本的命令（进阶）

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
TARGET_JENKINSFILE="Jenkinsfile"

# Type detection
bash "$SKILL_DIR/scripts/common_validation.sh" detect_type "$TARGET_JENKINSFILE"

# Syntax-only by type
bash "$SKILL_DIR/scripts/validate_declarative.sh" "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_scripted.sh" "$TARGET_JENKINSFILE"

# Security-only
bash "$SKILL_DIR/scripts/common_validation.sh" check_credentials "$TARGET_JENKINSFILE"

# Best-practices-only
bash "$SKILL_DIR/scripts/best_practices.sh" "$TARGET_JENKINSFILE"

退出代码和日志解读

主编排器：validate_jenkinsfile.sh

• 0：验证通过
• 1：验证失败（语法／安全错误，或 --strict 模式下的警告）
• 2：用法或环境错误（参数错误、缺少文件、缺少必需工具）

子脚本

• validate_declarative.sh：0 通过（错误数=0），1 用法／文件／验证失败
• validate_scripted.sh：0 通过（错误数=0），1 用法／文件／验证失败
• common_validation.sh check_credentials：0 未发现凭据错误，1 发现凭据问题
• validate_shared_library.sh：0 通过，1 发现验证错误，2 输入目标无效
• best_practices.sh：仅在用法／文件错误时返回 1；内容检查结果会显示在日志和评分输出中

日志严重性模式

• ERROR [Line N]: ... => 必须修复
• WARNING [Line N]: ... => 应进行检查
• INFO [Line N]: ... => 可选改进
• 摘要横幅（VALIDATION PASSED/FAILED）可帮助快速判断最终结果

实用解读规则

• 对于 CI 门禁，请以主编排器的退出代码为准。
• 当警告也应导致流水线失败时，请使用 --strict。
• 单独运行 best_practices.sh 时，请阅读报告部分（CRITICAL ISSUES、IMPROVEMENTS RECOMMENDED 和评分）；不要只依赖退出代码。

回退行为

缺少可选工具

• 如果缺少 jq，继续验证；将其视为非阻塞问题。

子脚本不可执行

• 主协调器会发出警告，并回退到通过 bash <script> 执行。

缺少子脚本

• 主协调器会报告运行器错误，并将该阶段标记为失败。

未知插件步骤

按以下顺序处理：

1. 检查本地参考资料：devops-skills-plugin/skills/jenkinsfile-validator/references/common_plugins.md
2. 查询 Context7：
   • 使用类似 jenkinsci <plugin-name>-plugin 的查询调用 mcp__context7__resolve-library-id
   • 使用 mcp__context7__query-docs 查询用法和参数
3. 回退到网络查询：plugins.jenkins.io 和 Jenkins 官方文档

离线／隔离网络模式

• 运行所有本地验证器。
• 如果无法获取插件文档，请报告：“由于环境限制，已跳过插件文档查询；仅进行了本地验证。”

插件文档查询工作流

当用户要求进行插件特定验证时：

1. 从 Jenkinsfile 或验证器日志中识别未知步骤。
2. 首先检查 references/common_plugins.md。
3. 如果没有相关内容，使用 Context7（先调用 resolve-library-id，再调用 query-docs）。
4. 如果仍未找到，使用网络搜索查询官方插件索引／文档。
5. 返回必需参数、可选参数、版本相关说明和安全指导。

参考资料

本地参考资料：

• devops-skills-plugin/skills/jenkinsfile-validator/references/declarative_syntax.md
• devops-skills-plugin/skills/jenkinsfile-validator/references/scripted_syntax.md
• devops-skills-plugin/skills/jenkinsfile-validator/references/best_practices.md
• devops-skills-plugin/skills/jenkinsfile-validator/references/common_plugins.md

外部参考资料：

• Jenkins Pipeline 语法
• Pipeline 开发工具
• Pipeline 最佳实践
• Jenkins 插件

报告模板

在验证响应中使用以下结构：

Validation Target: <path>
Pipeline Type: <Declarative|Scripted|Shared Library|Unknown>

Findings:
- ERROR [Line X]: <issue>
- WARNING [Line Y]: <issue>
- INFO [Line Z]: <suggestion>

Phase Results:
- Syntax: <PASSED|FAILED|SKIPPED>
- Security: <PASSED|FAILED|SKIPPED>
- Best Practices: <PASSED|REVIEW NEEDED|SKIPPED>

Exit Code: <0|1|2>
Next Actions:
1. <highest-priority fix>
2. <second fix>

示例流程

示例 1：完整 Jenkinsfile 验证

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" Jenkinsfile

预期行为：

• 运行语法、安全和最佳实践检查
• 输出各阶段结果和统一摘要
• 按照协调器规则返回 0/1/2

示例 2：共享库目录验证

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
bash "$SKILL_DIR/scripts/validate_shared_library.sh" examples/shared-library

预期行为：

• 验证 vars/ 和 src/ 中的所有文件
• 汇总问题并附上行号
• 存在错误时返回 1

示例 3：未知插件步骤后续处理

输入步骤：

nexusArtifactUploader artifacts: [[...]], nexusUrl: 'https://nexus.example.com'

流程：

1. 首先在本地进行验证。
2. 如果步骤行为不明确，通过 Context7 查询文档。
3. 如果无法获取文档，使用插件网站上的文档。
4. 报告用法指导和安全的参数模式。

完成标准

满足以下所有条件时，技能使用即告完成：

• 命令使用规范化路径（$SKILL_DIR/scripts/...），不存在当前工作目录歧义。
• 明确列出前置条件和可选依赖项。
• 记录退出码语义和日志严重级别的解读方式。
• 针对缺失的工具／文档和受限环境，定义回退行为。
• 至少提供一个可运行的完整验证示例和共享库验证示例。
• 报告格式明确、可执行且一致。