Jenkinsfile Validator Skill

Comprehensive toolkit for validating, linting, and testing Jenkinsfile pipelines (both Declarative and Scripted). This skill applies when working with Jenkins pipeline files, validating pipeline syntax, checking best practices, debugging pipeline issues, or working with custom plugins that require documentation lookup.

Validation Capabilities

Declarative: Required sections, directive placement, parallel execution, credential management, combined shell commands. Scripted: Groovy syntax, node blocks, try-catch-finally, NonCPS annotation usage, variable scoping. Both types: Hardcoded credential detection, controller-heavy operations (JsonSlurper, HttpRequest), variable declarations, plugin-specific step validation. Shared Library — vars/*.groovy: call() method, NonCPS annotation correctness, CPS compatibility, camelCase naming, documentation comments. src/**/*.groovy: package declaration, class-filename match, Serializable implementation, wildcard import warnings, static method CPS compatibility.

See references/validation_rules.md for detailed rules, error reporting format, and examples.

Pipeline Type Detection

Auto-detected: Declarative (pipeline {), Scripted (node block or Groovy outside pipeline block). Clarification is requested only if ambiguous.

Core Validation Workflow

Follow this workflow when validating Jenkinsfiles to catch issues early and ensure pipeline quality:

Quick Start - Full Validation (Recommended)

# Run complete validation (syntax + security + best practices)
bash scripts/validate_jenkinsfile.sh Jenkinsfile

This single command auto-detects pipeline type, runs syntax validation, a security scan (credential detection), and a best practices check, then produces a unified summary with pass/fail status.

Validation Options

# Full validation (default)
bash scripts/validate_jenkinsfile.sh Jenkinsfile

# Syntax validation only (fastest)
bash scripts/validate_jenkinsfile.sh --syntax-only Jenkinsfile

# Security audit only
bash scripts/validate_jenkinsfile.sh --security-only Jenkinsfile

# Best practices check only
bash scripts/validate_jenkinsfile.sh --best-practices Jenkinsfile

# Skip security checks
bash scripts/validate_jenkinsfile.sh --no-security Jenkinsfile

# Skip best practices
bash scripts/validate_jenkinsfile.sh --no-best-practices Jenkinsfile

# Strict mode (fail on warnings)
bash scripts/validate_jenkinsfile.sh --strict Jenkinsfile

Script Architecture

The validation system uses a modular script architecture:

scripts/
├── validate_jenkinsfile.sh      # Main orchestrator (USE THIS)
│   ├── Auto-detects pipeline type
│   ├── Runs syntax validation
│   ├── Runs security scan
│   ├── Runs best practices check
│   └── Produces unified summary
│
├── validate_declarative.sh      # Declarative syntax validator
├── validate_scripted.sh         # Scripted syntax validator
├── common_validation.sh         # Shared functions + security scan
├── best_practices.sh            # 15-point best practices scorer
└── validate_shared_library.sh   # Shared library validator

Key Point: Always use validate_jenkinsfile.sh as the main entry point - it orchestrates all other scripts automatically.

Shared Library Validation

Validate Jenkins Shared Library files using validate_shared_library.sh:

# Validate a single vars file
bash scripts/validate_shared_library.sh vars/myStep.groovy

# Validate entire shared library directory
bash scripts/validate_shared_library.sh /path/to/shared-library

Plugin Documentation Lookup

Important: Plugin documentation lookup is Claude's responsibility (not automated in scripts). After running validation, Claude should identify unknown plugins and look them up.

When to Look Up Plugin Documentation

Look up documentation when you encounter:

• Steps not in references/common_plugins.md (e.g., customDeploy, sendToDatadog, grafanaNotify)
• Plugin-specific configuration (e.g., nexusArtifactUploader, sonarQubeScanner)
• User questions about plugin parameters or best practices

Plugin Lookup Workflow (Claude's Responsibility)

1. Identify Unknown Plugin Step - Review Jenkinsfile for unrecognized steps
2. Check Local Reference First - Read: references/common_plugins.md
3. Use Context7 MCP (if not in local reference)
   • mcp__context7__resolve-library-id with query: "jenkinsci <plugin-name>-plugin"
   • mcp__context7__get-library-docs for usage examples and parameters
4. Web Search Fallback (if Context7 has no results)
   • WebSearch: "Jenkins <plugin-name> plugin documentation"
   • Official source: https://plugins.jenkins.io/
5. Provide Usage Guidance
   • Required vs optional parameters
   • Best practices for the plugin
   • Security considerations

See references/common_plugins.md for documentation on commonly used plugins.

Reference Documentation

• Declarative Syntax: Complete Declarative Pipeline syntax reference
• Scripted Syntax: Complete Scripted Pipeline syntax reference
• Best Practices: Jenkins pipeline best practices and patterns
• Common Plugins: Documentation for frequently used Jenkins plugins
• Validation Rules: Detailed validation rules, error reporting format, and examples
• Troubleshooting: Common issues, debug mode, and limitations

Usage Instructions

When a user provides a Jenkinsfile for validation:

1. Run the main validation script (recommended - handles everything automatically):

   bash scripts/validate_jenkinsfile.sh <path-to-jenkinsfile>

   This single command auto-detects pipeline type, runs syntax validation, security scan, and best practices check.

2. Optionally read the Jenkinsfile using the Read tool if you need to:

   • Understand the pipeline structure before validation
   • Provide context-specific advice
   • Identify specific plugins being used

3. After validation, scan for unknown plugins (Claude's responsibility):

   • Review the validation output for any unrecognized step names
   • Check references/common_plugins.md first for documentation
   • If not found, use Context7 MCP: mcp__context7__resolve-library-id with query "jenkinsci <plugin-name>"
   • If still not found, use WebSearch: "Jenkins <plugin-name> plugin documentation"
   • Provide usage guidance based on found documentation

4. Report results with line numbers, severity, and actionable suggestions

5. Provide inline fix suggestions when errors are found (do not use AskUserQuestion - include corrected code snippets directly in the response)

Tools Available

This skill uses standard shell scripts for validation. No special tools or external dependencies are required beyond:

• bash (for running validation scripts)
• Basic Unix utilities (grep, awk, sed)

Automatic Actions

When this skill is invoked:

1. Always validate syntax first (errors block execution)
2. Then check best practices (warnings for improvement)
3. Look up unknown plugins automatically
4. Provide actionable suggestions with every issue
5. Reference documentation files for detailed guidance

External References

• Official Jenkins Pipeline Syntax: https://www.jenkins.io/doc/book/pipeline/syntax/
• Pipeline Development Tools: https://www.jenkins.io/doc/book/pipeline/development/
• Pipeline Best Practices: https://www.jenkins.io/doc/book/pipeline/pipeline-best-practices/
• Jenkins Plugins: https://plugins.jenkins.io/