jenkinsfile-validator

Jenkinsfile Validator Skill

Use this skill to validate Jenkins pipelines and shared libraries with local scripts first, then optionally enrich findings with plugin documentation.

Trigger Phrases

Use this skill when requests look like:

"Validate this Jenkinsfile"
"Check this pipeline for security issues"
"Lint my Declarative/Scripted pipeline"
"Why is this Jenkins pipeline failing syntax checks?"
"Validate vars/.groovy or src/**/.groovy shared library files"

Scope

This skill validates:

Declarative pipelines (pipeline { ... })
Scripted pipelines (node { ... } and Groovy-style pipelines)
Shared library files (vars/*.groovy, src/**/*.groovy)
Hardcoded credential patterns
Pipeline best practices and maintainability signals

Prerequisites

Run commands from repository root unless noted.

Required tools

bash
grep
sed
awk
head
wc
find (needed for shared-library directory scans)

Recommended tools

jq (optional; improves JSON-heavy troubleshooting workflows)

Script prerequisites

Scripts live in devops-skills-plugin/skills/jenkinsfile-validator/scripts/
Main orchestrator can run child scripts even if +x is missing (it uses bash fallback)
If you want direct execution (./script.sh), make scripts executable:

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

Preflight check (recommended)

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"

Quick Start (Normalized Paths)

Use a single base path variable to avoid path ambiguity.

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

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

Common options

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"

Shared library validation

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

Regression and local CI checks

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

run_local_ci.sh is the supported local/CI entrypoint for regression coverage. It runs:

bash -n syntax checks for all scripts/*.sh and tests/*.sh files
tests/test_validate_jenkinsfile.sh regression scenarios

Deterministic Validation Flow

1) Detect pipeline type

pipeline { => Declarative validator
node (...) or node { => Scripted validator
Unknown => fails closed by default (ERROR [TypeDetection])
Override intentionally ambiguous files with --assume-declarative or --assume-scripted

2) Run syntax validation

Declarative: validate_declarative.sh
Scripted: validate_scripted.sh

3) Run security scan

common_validation.sh check_credentials

4) Run best practices check

best_practices.sh

5) Aggregate and return final status

Unified summary with pass/fail per phase and final exit code

6) Run regression suite after script changes

bash tests/run_local_ci.sh
Intended for both local pre-commit checks and CI job wiring

Individual Script Commands (Advanced)

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"

Exit Code and Log Interpretation

Main orchestrator: `validate_jenkinsfile.sh`

0: Validation passed
1: Validation failed (syntax/security errors, or warnings in --strict mode)
2: Usage or environment error (bad args, missing file, missing required tools)

Sub-scripts

validate_declarative.sh: 0 pass (errors=0), 1 usage/file/validation failure
validate_scripted.sh: 0 pass (errors=0), 1 usage/file/validation failure
common_validation.sh check_credentials: 0 no credential errors, 1 credential issues found
validate_shared_library.sh: 0 pass, 1 validation errors found, 2 invalid input target
best_practices.sh: 1 only for usage/file errors; content findings are reported in logs and score output

Log severity patterns

ERROR [Line N]: ... => must fix
WARNING [Line N]: ... => should review
INFO [Line N]: ... => optional improvement
Summary banners (VALIDATION PASSED/FAILED) determine final interpretation quickly

Practical interpretation rules

For CI gating, rely on main orchestrator exit code.
Use --strict when warnings should fail pipelines.
When best_practices.sh is run standalone, read report sections (CRITICAL ISSUES, IMPROVEMENTS RECOMMENDED, score); do not rely only on exit code.

Fallback Behavior

Missing optional tools

If jq is missing, continue validation; treat as non-blocking.

Non-executable child scripts

Main orchestrator warns and falls back to bash <script> execution.

Missing child scripts

Main orchestrator reports runner error and returns failure for that phase.

Unknown plugin steps

Use this order:

Check local reference: devops-skills-plugin/skills/jenkinsfile-validator/references/common_plugins.md
Context7 lookup:
- mcp__context7__resolve-library-id with query like jenkinsci <plugin-name>-plugin
- mcp__context7__query-docs for usage and parameters
Web fallback: plugins.jenkins.io and official Jenkins docs

Offline/air-gapped mode

Run all local validators.
If plugin docs cannot be fetched, report: "Plugin docs lookup skipped due to environment constraints; local validation only."

Plugin Documentation Lookup Workflow

When plugin-specific validation is requested:

Identify unknown steps from Jenkinsfile or validator logs.
Check references/common_plugins.md first.
If missing, use Context7 (resolve-library-id then query-docs).
If still missing, use web search against official plugin index/docs.
Return required parameters, optional parameters, version-sensitive notes, and security guidance.

References

Local references:

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

External references:

Reporting Template

Use this structure in validation responses:

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>

Example Flows

Example 1: Full Jenkinsfile validation

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

Expected behavior:

Runs syntax + security + best practices
Prints per-phase results and unified summary
Returns 0/1/2 per orchestrator rules

Example 2: Shared library directory validation

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