/jenkinsfile-validator

name: jenkinsfile-validator
description: Validate, lint, audit, or check Jenkinsfiles and shared libraries.

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` o