jenkinsfile-generator

Jenkinsfile 生成技能

按照最佳实践生成可用于生产环境的 Jenkinsfile。所有生成的文件都会使用 devops-skills:jenkinsfile-validator 技能进行验证。

触发短语

• “生成 Maven/Gradle/npm 的 CI 流水线”
• “创建带审批的 Jenkins 部署流水线”
• “构建包含并行测试阶段的 Jenkinsfile”
• “创建包含动态阶段逻辑的脚本式流水线”
• “搭建 Jenkins 共享库”
• “为 Docker 或 Kubernetes Agent 生成 Jenkinsfile”

使用场景

• 创建新的 Jenkinsfile（声明式或脚本式）
• CI/CD 流水线、Docker/Kubernetes 部署
• 并行执行、矩阵构建、参数化流水线
• 带安全扫描的 DevSecOps 流水线
• 搭建共享库

声明式与脚本式决策树

1. 当阶段顺序和行为大多固定时，默认选择声明式。
2. 当需要运行时生成阶段、复杂循环或动态控制流时，选择脚本式。
3. 当请求涉及可复用的流水线函数（vars/、src/、resources/）时，选择共享库搭建。
4. 如果不确定，先采用声明式；只有在需求无法清晰表达时才切换到脚本式。

模板索引

模板	路径	使用场景
基础声明式	assets/templates/declarative/basic.Jenkinsfile	阶段可预测的标准 CI/CD
声明式并行示例	examples/declarative-parallel.Jenkinsfile	具有快速失败行为的并行测试/构建分支
声明式 Kubernetes 示例	examples/declarative-kubernetes.Jenkinsfile	使用 Pod 模板通过 Kubernetes Agent 执行
基础脚本式	assets/templates/scripted/basic.Jenkinsfile	复杂条件逻辑或生成阶段
共享库脚手架	由 scripts/generate_shared_library.py 生成	可复用的流水线函数和组织范围的模式

快速参考

// 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' }
}

选项	用途
timeout(time: 1, unit: 'HOURS')	防止构建卡住
buildDiscarder(logRotator(numToKeepStr: '10'))	管理磁盘空间
disableConcurrentBuilds()	防止竞态条件
catchError(buildResult: 'SUCCESS', stageResult: 'FAILURE')	出错时继续执行

核心能力

1. 声明式流水线（推荐）

流程：

1. 阅读模板以参考结构：
   • 阅读 assets/templates/declarative/basic.Jenkinsfile，了解标准结构
   • 模板展示了预期的各个部分：pipeline → agent → environment → options → parameters → stages → post
   • 对于复杂请求，应调整结构，而不是逐字照搬
2. 查阅参考文档：
   • 阅读 references/best_practices.md，了解性能、安全性和可靠性模式
   • 阅读 references/common_plugins.md，了解特定插件的语法
3. 生成时包含必需元素：
   • 具有描述性名称的适当阶段
   • 包含凭据绑定的 environment 块（绝不硬编码密钥）
   • 选项：timeout、buildDiscarder、timestamps、disableConcurrentBuilds
   • Post 条件：always（清理）、success（构件）、failure（通知）
   • 并行块始终添加 failFast true 或 parallelsAlwaysFailFast()
   • 使用 archiveArtifacts 时始终包含 fingerprint: true
4. 始终使用 devops-skills:jenkinsfile-validator 技能进行验证

2. 脚本式流水线

适用场景： 复杂条件逻辑、动态生成、完整的 Groovy 控制能力 流程：

1. 阅读模板以参考结构：
   • 阅读 assets/templates/scripted/basic.Jenkinsfile，了解 node/stage 模式
   • 理解用于错误处理的 try-catch-finally 结构
2. 使用 try-catch-finally 进行错误处理
3. 始终使用 devops-skills:jenkinsfile-validator 技能进行验证

3. 并行／矩阵流水线

使用 parallel {} 块，或使用带有 axes {} 的 matrix {} 进行多维构建。

• 生成的并行流水线默认采用快速失败行为（parallelsAlwaysFailFast() 或阶段级 failFast true）。

4. 安全扫描（DevSecOps）

添加 SonarQube、OWASP Dependency-Check 和 Trivy 阶段，并设置失败阈值。

5. 共享库脚手架

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

声明式语法参考

Agent 类型

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 {
    VERSION = '1.0.0'
    AWS_KEY = credentials('aws-key-id')     // Creates _USR and _PSW vars
}

选项

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

参数

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

When 条件

条件	示例
branch	branch 'main' 或 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	组合条件

添加 beforeAgent true，在条件不满足时跳过 Agent 分配。

错误处理

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 部分

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

顺序： always → changed → fixed → regression → failure → success → unstable → cleanup

注意： 始终在 archiveArtifacts 中使用 fingerprint: true，以便追踪构建和管理制品。

并行与矩阵

重要： 始终确保并行块在首次失败时快速失败，可采用以下任一方法：

选项 1：全局（推荐） - 在流水线选项中使用 parallelsAlwaysFailFast()：

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

这是首选方法，因为它会自动涵盖所有并行块。

选项 2：逐块设置 - 在各个并行阶段上使用 failFast true：

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

注意： 在选项中设置了 parallelsAlwaysFailFast() 后，各个并行块上的显式 failFast true 就是多余的。

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}" } } }
    }
}

输入（手动批准）

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

重要： 将 input 放在 steps 外部，以避免占用 Agent。

脚本式语法参考

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

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

规则： 不要在 @NonCPS 中使用流水线步骤（sh、echo）。将其用于 JsonSlurper、迭代器和正则表达式 Matchers。

Docker 与 Kubernetes

Docker Agent

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

构建与推送

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' }

共享库

@Library('my-shared-library') _
// or dynamically: library '[email protected]'

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

// Usage
log.info 'Starting build'

验证工作流

关键：始终使用 devops-skills:jenkinsfile-validator 技能进行验证：

1. 生成 Jenkinsfile
2. 调用 devops-skills:jenkinsfile-validator 技能
3. 按严重级别处理验证结果：
   • 错误： 必须在向用户展示前修复，否则会导致流水线无法运行
   • 警告： 应当修复，这些问题可能造成隐患
   • 信息／建议： 根据具体用途考虑是否采纳：
     • 并行块使用 failFast true → 默认采纳
     • 构建触发器 → 询问用户是否需要自动构建
     • 其他优化 → 如果能改进流水线，则予以采纳
4. 修复后重新验证
5. 只向用户展示经过验证的 Jenkinsfile

验证命令：

# 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

生成器脚本

何时使用脚本，何时手动生成：

• 适合使用脚本： 使用常见模式的简单、标准流水线（基础 CI、简单的 CD）
• 适合手动生成： 包含多项功能的复杂流水线（并行测试 + 安全扫描 + Docker + K8s 部署）、自定义逻辑或非标准需求

脚本参数：必需与可选

• generate_declarative.py
• 必需：--output
• 可选：--stages、--agent、--build-tool、--build-cmd、--test-cmd、--deploy-*、--notification-*、--archive-artifacts、--k8s-yaml
• 说明：
• --k8s-yaml 接受内联 YAML 内容或现有 .yaml/.yml 文件的路径。
• 阶段键会经过验证（[a-z0-9_-]），shell 命令会作为转义后的 Groovy 字面量输出。
• generate_scripted.py
• 必需：--output
• 可选：根据请求的流水线功能，提供阶段、Agent、SCM 和通知参数。
• generate_shared_library.py
• 必需：--name
• 可选：--package、--output
• 共享库部署助手现在会显式指定 rollout 目标（deployment/<name>），通知助手会生成有效的 HTML 邮件正文。

# 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

完成标准

• 明确选择流水线风格（Declarative 或 Scripted），并说明理由。
• 生成的 Jenkinsfile 通过冒烟验证，且验证命令可执行。
• 默认情况下，并行流水线会快速失败，除非用户明确要求其他行为。
• 自定义阶段名称和 shell 命令会安全输出（不会产生未转义的 Groovy 字面量）。
• --k8s-yaml 同时支持内联 YAML 和现有文件路径。
• 启用通知的 post 块仍会在请求时归档构件。

插件文档查询

始终使用 Context7 或 WebSearch 查询以下内容：

• references/common_plugins.md 中未涵盖的插件
• 特定版本的文档请求
• 复杂的插件配置或高级选项
• 用户明确要求最新文档时

以下情况可以跳过外部查询：

• 使用 references/common_plugins.md 中已有文档说明的基本插件语法
• 简单且文档完善的插件步骤（例如基本的 sh、checkout scm、junit）

common_plugins.md 中涵盖的插件： Git、Docker、Kubernetes、Credentials、JUnit、Slack、SonarQube、OWASP Dependency-Check、Email、AWS、Azure、HTTP Request、Microsoft Teams、Nexus、Artifactory、GitHub

查询方法（按优先顺序）：

1. Context7： 使用 /jenkinsci/<plugin-name>-plugin 调用 mcp__context7__resolve-library-id
2. WebSearch： Jenkins [plugin-name] plugin documentation 2025
3. 官方文档： plugins.jenkins.io、jenkins.io/doc/pipeline/steps/

参考资料

• references/best_practices.md - 性能、安全性和可靠性模式
• references/common_plugins.md - Git、Docker、K8s、凭据、通知
• assets/templates/ - Declarative 和 scripted 模板
• devops-skills:jenkinsfile-validator 技能 - 语法和最佳实践验证

除非需要 scripted 的灵活性，否则始终优先使用 Declarative。