jenkinsfile-validator

name	jenkinsfile-validator
description	Comprehensive toolkit for validating, linting, testing, and automating Jenkinsfile pipelines (both Declarative and Scripted). Use this skill when working with Jenkins pipeline files, validating pipeline syntax, checking best practices, debugging pipeline issues, or working with custom plugins.

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.

When to Use This Skill

Use this skill when you need to:

• Validate a Jenkinsfile (Declarative or Scripted) for syntax and best practices.
• Run the Declarative Linter against a Declarative pipeline.
• Check Shared Library calls the pipeline depends on.
• Detect hardcoded credentials or controller-heavy operations in a pipeline.

When NOT to use this skill:

• Authoring a new Jenkinsfile from scratch — use jenkinsfile-generator instead.
• CI configuration for a non-Jenkins system (GitHub Actions, GitLab CI) — use that system's skill.
• Diagnosing a failed build's application logs rather than the pipeline definition.

Mindset

• Detect the type first. Declarative and Scripted have different rules; validate against the right one.
• Lint even when it looks fine. Run the Declarative Linter rather than eyeballing syntax.
• Follow the calls. A Jenkinsfile is incomplete without the Shared Library steps it invokes; validate those too.
• Look up unfamiliar steps. Judge a non-core plugin step against its documentation, not an assumption.

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.

Validation Command Reference

Full Validation (Recommended)

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

Auto-detects pipeline type, validates syntax, scans for hardcoded credentials, checks best practices, and produces a unified summary.

Command 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

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.

Claude's Workflow

When a user provides a Jenkinsfile for validation:

1. Run validation using the main script:

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

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. Look up unknown plugins after validation:

   • Review validation output for unrecognized step names
   • Check references/common_plugins.md first
   • 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 documentation

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

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

Anti-Patterns

NEVER validate only the Jenkinsfile without checking Shared Library calls

• WHY: Pipeline files that reference shared library steps pass basic validation but fail at runtime when the library step has changed signature.
• BAD: Validate Jenkinsfile in isolation when it calls @Library('my-lib') import com.example.Build.
• GOOD: Note all @Library calls and cross-reference the library version being loaded.

NEVER skip Declarative Linter validation for Declarative pipelines

• WHY: The Jenkins Declarative Linter catches structural errors that generic YAML/Groovy checks miss, such as missing steps blocks or invalid directive placement.
• BAD: Rely only on Groovy syntax checking for Declarative pipelines.
• GOOD: Submit the Jenkinsfile to http://<jenkins>/pipeline-model-converter/validate or use the CLI linter.

NEVER accept a "no errors" result from a linter as a green-light to deploy

• WHY: Linters cannot execute the pipeline; validate that sh steps, credentials references, and environment variables exist in the target Jenkins environment.
• BAD: Merge pipeline changes based only on linter results.
• GOOD: Run the pipeline against a staging branch with a dry-run or canary job before merging to main.

NEVER leave retry(n) in production pipelines without understanding why it was added

• WHY: Retry masks flaky steps and increases build time; investigate the root cause instead.
• BAD: Add retry(3) to a flaky test stage and close the ticket.
• GOOD: Investigate why the step is flaky, fix the root cause, and remove the retry.

References

Internal:

• 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

External:

• 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/