Jenkinsfile Generator Skill

Generate production-ready Jenkinsfiles following best practices. All generated files are validated using devops-skills:jenkinsfile-validator skill.

Trigger Phrases

• "Generate a CI pipeline for Maven/Gradle/npm"

• "Create a Jenkins deployment pipeline with approvals"

• "Build a Jenkinsfile with parallel test stages"

• "Create a scripted pipeline with dynamic stage logic"

• "Scaffold a Jenkins shared library"

• "Generate a Jenkinsfile for Docker or Kubernetes agents"

When to Use

• Creating new Jenkinsfiles (declarative or scripted)

• CI/CD pipelines, Docker/Kubernetes deployments

• Parallel execution, matrix builds, parameterized pipelines

• DevSecOps pipelines with security scanning

• Shared library scaffolding

Declarative vs Scripted Decision Tree

• Choose Declarative by default when stage order and behavior are mostly static.

• Choose Scripted when runtime-generated stages, complex loops, or dynamic control flow are required.

• Choose Shared Library scaffolding when request is about reusable pipeline functions (vars/ , src/ , resources/ ).

• If unsure, start Declarative and only switch to Scripted if requirements cannot be expressed cleanly.

Template Map

Template Path Use When

Declarative basic assets/templates/declarative/basic.Jenkinsfile

Standard CI/CD with predictable stages

Declarative parallel example examples/declarative-parallel.Jenkinsfile

Parallel test/build branches with fail-fast behavior

Declarative kubernetes example examples/declarative-kubernetes.Jenkinsfile

Kubernetes agent execution using pod templates

Scripted basic assets/templates/scripted/basic.Jenkinsfile

Complex conditional logic or generated stages

Shared library scaffold Generated by scripts/generate_shared_library.py

Reusable pipeline functions and organization-wide patterns

Quick Reference

// Minimal Declarative Pipeline pipeline { agent any stages { stage('Build') { steps { sh 'make' } } stage('Test') { steps { sh 'make test' } } } }

// Error-tolerant stage stage('Flaky Tests') { steps { catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') { sh 'run-flaky-tests.sh' } } }

// Conditional deployment with approval stage('Deploy') { when { branch 'main'; beforeAgent true } input { message 'Deploy to production?' } steps { sh './deploy.sh' } }

Option Purpose

timeout(time: 1, unit: 'HOURS')

Prevent hung builds

buildDiscarder(logRotator(numToKeepStr: '10'))

Manage disk space

disableConcurrentBuilds()

Prevent race conditions

catchError(buildResult: 'SUCCESS', stageResult: 'FAILURE')

Continue on error

Core Capabilities

1. Declarative Pipelines (RECOMMENDED)

Process:

• Read templates for structure reference:

• Read assets/templates/declarative/basic.Jenkinsfile to understand the standard structure

• Templates show the expected sections: pipeline → agent → environment → options → parameters → stages → post

• For complex requests, adapt the structure rather than copying verbatim

• Consult reference documentation:

• Read references/best_practices.md for performance, security, and reliability patterns

• Read references/common_plugins.md for plugin-specific syntax

• Generate with required elements:

• Proper stages with descriptive names

• Environment block with credentials binding (never hardcode secrets)

• Options: timeout, buildDiscarder, timestamps, disableConcurrentBuilds

• Post conditions: always (cleanup), success (artifacts), failure (notifications)

• Always add failFast true or parallelsAlwaysFailFast() for parallel blocks

• Always include fingerprint: true when using archiveArtifacts

• ALWAYS validate using devops-skills:jenkinsfile-validator skill

2. Scripted Pipelines

When: Complex conditional logic, dynamic generation, full Groovy control Process:

• Read templates for structure reference:

• Read assets/templates/scripted/basic.Jenkinsfile for node/stage patterns

• Understand try-catch-finally structure for error handling

• Implement try-catch-finally for error handling

• ALWAYS validate using devops-skills:jenkinsfile-validator skill

3. Parallel/Matrix Pipelines

Use parallel {} block or matrix {} with axes {} for multi-dimensional builds.

• Default behavior is fail-fast for generated parallel pipelines (parallelsAlwaysFailFast() or stage-level failFast true ).

4. Security Scanning (DevSecOps)

Add SonarQube, OWASP Dependency-Check, Trivy stages with fail thresholds.

5. Shared Library Scaffolding

python3 scripts/generate_shared_library.py --name my-library --package org.example

Declarative Syntax Reference

Agent Types

agent any // Any available agent agent { label 'linux && docker' } // Label-based agent { docker { image 'maven:3.9.11-eclipse-temurin-21' } } agent { kubernetes { yaml '...' } } // K8s pod template agent { kubernetes { yamlFile 'pod.yaml' } } // External YAML

Environment & Credentials

environment { VERSION = '1.0.0' AWS_KEY = credentials('aws-key-id') // Creates _USR and _PSW vars }

Options

options { buildDiscarder(logRotator(numToKeepStr: '10')) timeout(time: 1, unit: 'HOURS') disableConcurrentBuilds() timestamps() parallelsAlwaysFailFast() durabilityHint('PERFORMANCE_OPTIMIZED') // 2-6x faster for simple pipelines }

Parameters

parameters { string(name: 'VERSION', defaultValue: '1.0.0') choice(name: 'ENV', choices: ['dev', 'staging', 'prod']) booleanParam(name: 'SKIP_TESTS', defaultValue: false) }

When Conditions

Condition Example

branch

branch 'main' or branch pattern: 'release/*', comparator: 'GLOB'

tag

tag pattern: 'v*', comparator: 'GLOB'

changeRequest

changeRequest target: 'main'

changeset

changeset 'src/**/*.java'

expression

expression { env.DEPLOY == 'true' }

allOf/anyOf/not

Combine conditions

Add beforeAgent true to skip agent allocation if condition fails.

Error Handling

catchError(buildResult: 'UNSTABLE', stageResult: 'FAILURE') { sh '...' } warnError('msg') { sh '...' } // Mark UNSTABLE but continue unstable(message: 'Coverage low') // Explicit UNSTABLE error('Config missing') // Fail without stack trace

Post Section

post { always { junit '/target/*.xml'; cleanWs() } success { archiveArtifacts artifacts: '/*.jar', fingerprint: true } failure { slackSend color: 'danger', message: 'Build failed' } fixed { echo 'Build fixed!' } }

Order: always → changed → fixed → regression → failure → success → unstable → cleanup

NOTE: Always use fingerprint: true with archiveArtifacts for build traceability and artifact tracking.

Parallel & Matrix

IMPORTANT: Always ensure parallel blocks fail fast on first failure using one of these approaches:

Option 1: Global (RECOMMENDED) - Use parallelsAlwaysFailFast() in pipeline options:

options { parallelsAlwaysFailFast() // Applies to ALL parallel blocks in pipeline }

This is the preferred approach as it covers all parallel blocks automatically.

Option 2: Per-block - Use failFast true on individual parallel stages:

stage('Tests') { failFast true // Only affects this parallel block parallel { stage('Unit') { steps { sh 'npm test:unit' } } stage('E2E') { steps { sh 'npm test:e2e' } } } }

NOTE: When parallelsAlwaysFailFast() is set in options, explicit failFast true on individual parallel blocks is redundant.

stage('Matrix') { failFast true matrix { axes { axis { name 'PLATFORM'; values 'linux', 'windows' } axis { name 'BROWSER'; values 'chrome', 'firefox' } } excludes { exclude { axis { name 'PLATFORM'; values 'linux' }; axis { name 'BROWSER'; values 'safari' } } } stages { stage('Test') { steps { echo "Testing ${PLATFORM}/${BROWSER}" } } } } }

Input (Manual Approval)

stage('Deploy') { input { message 'Deploy?'; ok 'Deploy'; submitter 'admin,ops' } steps { sh './deploy.sh' } }

IMPORTANT: Place input outside steps to avoid holding agents.

Scripted Syntax Reference

node('agent-label') { try { stage('Build') { sh 'make build' } stage('Test') { sh 'make test' } } catch (Exception e) { currentBuild.result = 'FAILURE' throw e } finally { deleteDir() } }

// Parallel parallel( 'Unit': { node { sh 'npm test:unit' } }, 'E2E': { node { sh 'npm test:e2e' } } )

// Environment withEnv(['VERSION=1.0.0']) { sh 'echo $VERSION' } withCredentials([string(credentialsId: 'key', variable: 'KEY')]) { sh 'curl -H "Auth: $KEY" ...' }

@NonCPS for Non-Serializable Operations

@NonCPS def parseJson(String json) { new groovy.json.JsonSlurper().parseText(json) }

Rules: No pipeline steps (sh , echo ) inside @NonCPS. Use for JsonSlurper, iterators, regex Matchers.

Docker & Kubernetes

Docker Agent

agent { docker { image 'maven:3.9.11'; args '-v $HOME/.m2:/root/.m2'; reuseNode true } }

Build & Push

def img = docker.build("myapp:${BUILD_NUMBER}") docker.withRegistry('https://registry.example.com', 'creds') { img.push(); img.push('latest') }

Kubernetes Pod

agent { kubernetes { yaml ''' apiVersion: v1 kind: Pod spec: containers:

• name: maven image: maven:3.9.11-eclipse-temurin-21 command: [sleep, 99d] ''' } } // Use: container('maven') { sh 'mvn package' }

Shared Libraries

@Library('my-shared-library') _ // or dynamically: library 'my-library@1.0.0'

// vars/log.groovy def info(msg) { echo "INFO: ${msg}" }

// Usage log.info 'Starting build'

Validation Workflow

CRITICAL: ALWAYS validate using devops-skills:jenkinsfile-validator skill:

• Generate Jenkinsfile

• Invoke devops-skills:jenkinsfile-validator skill

• Handle validation results by severity:

• ERRORS: MUST fix before presenting to user - these break the pipeline

• WARNINGS: SHOULD fix - these indicate potential issues

• INFO/SUGGESTIONS: Consider applying based on use case:

• failFast true for parallel blocks → apply by default

• Build triggers → ask user if they want automated builds

• Other optimizations → apply if they improve the pipeline

• Re-validate after fixes

• Only present validated Jenkinsfiles to user

Validation commands:

Full validation (syntax + security + best practices)

bash ../jenkinsfile-validator/scripts/validate_jenkinsfile.sh Jenkinsfile

Syntax only (fastest)

bash ../jenkinsfile-validator/scripts/validate_jenkinsfile.sh --syntax-only Jenkinsfile

Generator Scripts

When to use scripts vs manual generation:

• Use scripts for: Simple, standard pipelines with common patterns (basic CI, straightforward CD)

• Use manual generation for: Complex pipelines with multiple features (parallel tests + security scanning + Docker + K8s deployments), custom logic, or non-standard requirements

Script Arguments: Required vs Optional

• generate_declarative.py

• Required: --output

• Optional: --stages , --agent , --build-tool , --build-cmd , --test-cmd , --deploy-* , --notification-* , --archive-artifacts , --k8s-yaml

• Notes:

• --k8s-yaml accepts either inline YAML content or a path to an existing .yaml /.yml file.

• Stage keys are validated ([a-z0-9_-] ) and shell commands are emitted as escaped Groovy literals.

• generate_scripted.py

• Required: --output

• Optional: stage/agent/SCM/notification parameters depending on requested pipeline features.

• generate_shared_library.py

• Required: --name

• Optional: --package , --output

• Shared library deployment helper now includes explicit rollout target (deployment/<name> ) and notification helper emits valid HTML email bodies.

Declarative (simple pipelines)

python3 scripts/generate_declarative.py --output Jenkinsfile --stages build,test,deploy --agent docker

Scripted (simple pipelines)

python3 scripts/generate_scripted.py --output Jenkinsfile --stages build,test --agent label:linux

Shared Library (always use script for scaffolding)

python3 scripts/generate_shared_library.py --name my-library --package com.example

Done Criteria

• Pipeline style selection (Declarative vs Scripted) is explicit and justified.

• Generated Jenkinsfiles pass smoke validation with executable validator commands.

• Parallel pipelines are fail-fast by default unless user explicitly requests otherwise.

• Custom stage names and shell commands are safely emitted (no unescaped Groovy literals).

• --k8s-yaml works with both inline YAML and existing file paths.

• Notification-enabled post blocks still archive artifacts when requested.

Plugin Documentation Lookup

Always consult Context7 or WebSearch for:

• Plugins NOT covered in references/common_plugins.md

• Version-specific documentation requests

• Complex plugin configurations or advanced options

• When user explicitly asks for latest documentation

May skip external lookup when:

• Using basic plugin syntax already documented in references/common_plugins.md

• Simple, well-documented plugin steps (e.g., basic sh , checkout scm , junit )

Plugins covered in common_plugins.md: Git, Docker, Kubernetes, Credentials, JUnit, Slack, SonarQube, OWASP Dependency-Check, Email, AWS, Azure, HTTP Request, Microsoft Teams, Nexus, Artifactory, GitHub

Lookup methods (in order of preference):

• Context7: mcp__context7__resolve-library-id with /jenkinsci/<plugin-name>-plugin

• WebSearch: Jenkins [plugin-name] plugin documentation 2025

• Official: plugins.jenkins.io, jenkins.io/doc/pipeline/steps/

References

• references/best_practices.md

• Performance, security, reliability patterns

• references/common_plugins.md

• Git, Docker, K8s, credentials, notifications

• assets/templates/

• Declarative and scripted templates

• devops-skills:jenkinsfile-validator skill - Syntax and best practices validation

Always prefer Declarative unless scripted flexibility is required.