jenkinsfile-generator

Jenkinsfile ジェネレーター スキル

ベストプラクティスに従って、本番環境で使える Jenkinsfile を生成します。生成したファイルはすべて、devops-skills:jenkinsfile-validator スキルを使って検証されます。

トリガーフレーズ

• 「Maven／Gradle／npm 向けの CI パイプラインを生成して」
• 「承認プロセスのある Jenkins デプロイパイプラインを作成して」
• 「並列テストステージを含む Jenkinsfile を作成して」
• 「動的なステージロジックを含む Scripted パイプラインを作成して」
• 「Jenkins 共有ライブラリのひな形を作成して」
• 「Docker または Kubernetes エージェント向けの Jenkinsfile を生成して」

使用するタイミング

• 新しい Jenkinsfile（Declarative または Scripted）の作成
• CI/CD パイプライン、Docker／Kubernetes のデプロイ
• 並列実行、マトリックスビルド、パラメーター化されたパイプライン
• セキュリティスキャンを含む DevSecOps パイプライン
• 共有ライブラリのひな形作成

Declarative と Scripted の選択フローチャート

1. ステージの順序と動作がほぼ固定の場合は、デフォルトで Declarative を選択します。
2. 実行時に生成されるステージ、複雑なループ、または動的な制御フローが必要な場合は、Scripted を選択します。
3. 再利用可能なパイプライン関数（vars/、src/、resources/）に関するリクエストの場合は、共有ライブラリのひな形を選択します。
4. 判断に迷う場合は Declarative から始め、要件を簡潔に表現できない場合にのみ Scripted に切り替えます。

テンプレート一覧

テンプレート	パス	使用するタイミング
Declarative 基本	assets/templates/declarative/basic.Jenkinsfile	予測可能なステージを含む標準的な CI/CD
Declarative 並列実行の例	examples/declarative-parallel.Jenkinsfile	フェイルファスト動作を備えた並列テスト／ビルドブランチ
Declarative Kubernetes の例	examples/declarative-kubernetes.Jenkinsfile	Pod テンプレートを使った Kubernetes エージェントでの実行
Scripted 基本	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. Declarative パイプライン（推奨）

手順：

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. Scripted パイプライン

使用する状況： 複雑な条件ロジック、動的な生成、完全な Groovy 制御が必要な場合 手順：

1. 構成の参考としてテンプレートを読む：
   • ノード／ステージのパターンについて、assets/templates/scripted/basic.Jenkinsfile を読みます
   • エラー処理のための 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 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 を追加します。

エラー処理

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

Input（手動承認）

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

重要： エージェントを占有しないよう、input は steps の外に配置します。

スクリプト型構文のリファレンス

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、イテレーター、正規表現の Matcher に使用します。

Docker と Kubernetes

Docker エージェント

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_-]）、シェルコマンドはエスケープされた Groovy リテラルとして出力されます。
• generate_scripted.py
• 必須：--output
• 任意：要求されたパイプライン機能に応じたステージ／エージェント／SCM／通知パラメーター。
• generate_shared_library.py
• 必須：--name
• 任意：--package、--output
• 共有ライブラリのデプロイヘルパーには、明示的なロールアウト対象（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 は、実行可能なバリデーターコマンドでスモーク検証に合格します。
• ユーザーが明示的に別の動作を要求しない限り、並列パイプラインはデフォルトでフェイルファストになります。
• カスタムステージ名とシェルコマンドは安全に出力されます（エスケープされていない 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 を優先してください。