jenkinsfile-validator

Jenkinsfile Validator Skill

このスキルを使用すると、まずローカルスクリプトで Jenkins パイプラインと共有ライブラリを検証し、その後、必要に応じてプラグインのドキュメントで検出結果を補足できます。

トリガーフレーズ

次のようなリクエストがあった場合に、このスキルを使用します。

• 「この Jenkinsfile を検証して」
• 「このパイプラインにセキュリティ上の問題がないか確認して」
• 「Declarative／Scripted パイプラインをリントして」
• 「この Jenkins パイプラインが構文チェックに失敗するのはなぜですか？」
• 「vars/.groovy または src/**/.groovy の共有ライブラリファイルを検証して」

対象範囲

このスキルでは、次を検証します。

• Declarative パイプライン（pipeline { ... }）
• Scripted パイプライン（node { ... } および Groovy 形式のパイプライン）
• 共有ライブラリファイル（vars/*.groovy、src/**/*.groovy）
• ハードコードされた認証情報のパターン
• パイプラインのベストプラクティスと保守性に関する指標

前提条件

特に記載がない限り、リポジトリのルートからコマンドを実行してください。

必須ツール

• bash
• grep
• sed
• awk
• head
• wc
• find（共有ライブラリのディレクトリスキャンに必要）

推奨ツール

• jq（任意。JSON を多く扱うトラブルシューティングのワークフローを改善できます）

スクリプトの前提条件

• スクリプトは devops-skills-plugin/skills/jenkinsfile-validator/scripts/ にあります
• メインのオーケストレーターは、+x が設定されていなくても子スクリプトを実行できます（bash にフォールバックします）
• 直接実行（./script.sh）する場合は、スクリプトに実行権限を付与してください。

chmod +x devops-skills-plugin/skills/jenkinsfile-validator/scripts/*.sh

事前チェック（推奨）

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"

command -v bash grep sed awk head wc find >/dev/null && echo "required tools: ok" || echo "required tools: missing"
command -v jq >/dev/null && echo "jq: installed (optional)" || echo "jq: missing (optional)"

[ -d "$SKILL_DIR/scripts" ] && echo "scripts dir: ok" || echo "scripts dir: missing"
[ -f "$SKILL_DIR/scripts/validate_jenkinsfile.sh" ] && echo "main validator: ok" || echo "main validator: missing"

クイックスタート（正規化されたパス）

パスの曖昧さを避けるため、単一のベースパス変数を使用します。

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
TARGET_JENKINSFILE="Jenkinsfile"

# Full validation (recommended)
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" "$TARGET_JENKINSFILE"

よく使うオプション

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
TARGET_JENKINSFILE="Jenkinsfile"

bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --syntax-only "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --security-only "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --best-practices "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --no-security "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --no-best-practices "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --strict "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --assume-declarative "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" --assume-scripted "$TARGET_JENKINSFILE"

共有ライブラリの検証

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"

bash "$SKILL_DIR/scripts/validate_shared_library.sh" vars/myStep.groovy
bash "$SKILL_DIR/scripts/validate_shared_library.sh" vars/
bash "$SKILL_DIR/scripts/validate_shared_library.sh" src/
bash "$SKILL_DIR/scripts/validate_shared_library.sh" /path/to/shared-library

回帰テストとローカル CI チェック

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
bash "$SKILL_DIR/tests/run_local_ci.sh"

run_local_ci.sh は、回帰テストを実行するためにサポートされているローカル／CI のエントリーポイントです。次を実行します。

• すべての scripts/*.sh ファイルと tests/*.sh ファイルに対する bash -n 構文チェック
• tests/test_validate_jenkinsfile.sh の回帰シナリオ

決定論的な検証フロー

1）パイプラインの種類を検出

• pipeline { => Declarative バリデーター
• node (...) または node { => Scripted バリデーター
• 不明 => デフォルトでは安全側に失敗します（ERROR [TypeDetection]）
• 意図的に判定が曖昧なファイルには、--assume-declarative または --assume-scripted で種類を指定します

2）構文を検証

• Declarative：validate_declarative.sh
• Scripted：validate_scripted.sh

3）セキュリティスキャンを実行

• common_validation.sh check_credentials

4）ベストプラクティスを確認

• best_practices.sh

5）結果を集約し、最終ステータスを返す

• 各フェーズの成功／失敗と最終終了コードを含む統一サマリー

6）スクリプト変更後に回帰テストスイートを実行

• bash tests/run_local_ci.sh
• ローカルのコミット前チェックと CI ジョブへの組み込みの両方を想定しています

個別スクリプトのコマンド（上級者向け）

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
TARGET_JENKINSFILE="Jenkinsfile"

# Type detection
bash "$SKILL_DIR/scripts/common_validation.sh" detect_type "$TARGET_JENKINSFILE"

# Syntax-only by type
bash "$SKILL_DIR/scripts/validate_declarative.sh" "$TARGET_JENKINSFILE"
bash "$SKILL_DIR/scripts/validate_scripted.sh" "$TARGET_JENKINSFILE"

# Security-only
bash "$SKILL_DIR/scripts/common_validation.sh" check_credentials "$TARGET_JENKINSFILE"

# Best-practices-only
bash "$SKILL_DIR/scripts/best_practices.sh" "$TARGET_JENKINSFILE"

終了コードとログの解釈

メインオーケストレーター：validate_jenkinsfile.sh

• 0：検証に合格
• 1：検証に失敗（構文／セキュリティエラー、または --strict モードでの警告）
• 2：使用方法または環境に関するエラー（引数の誤り、ファイルがない、必須ツールがない）

サブスクリプト

• validate_declarative.sh：0 合格（errors=0）、1 使用方法／ファイル／検証エラー
• validate_scripted.sh：0 合格（errors=0）、1 使用方法／ファイル／検証エラー
• common_validation.sh check_credentials：0 認証情報のエラーなし、1 認証情報の問題を検出
• validate_shared_library.sh：0 合格、1 検証エラーを検出、2 入力対象が無効
• best_practices.sh：1 になるのは使用方法／ファイルのエラーのみ。内容に関する検出結果はログとスコア出力に報告されます

ログの重要度パターン

• ERROR [Line N]: ... => 修正が必要です
• WARNING [Line N]: ... => 確認が必要です
• INFO [Line N]: ... => 任意の改善項目です
• サマリーバナー（VALIDATION PASSED/FAILED）を見ると、最終結果をすばやく判断できます

実用的な解釈ルール

• CI のゲートでは、メインオーケストレーターの終了コードを基準にしてください。
• 警告でパイプラインを失敗させる場合は、--strict を使用してください。
• best_practices.sh を単独で実行する場合は、終了コードだけに頼らず、レポートの各セクション（CRITICAL ISSUES、IMPROVEMENTS RECOMMENDED、スコア）を確認してください。

フォールバック動作

不足しているオプションのツール

• jq が見つからない場合も、検証を続行します。ブロッキング要因として扱いません。

実行権限のない子スクリプト

• メインオーケストレーターが警告を出し、bash <script> による実行にフォールバックします。

見つからない子スクリプト

• メインオーケストレーターはランナーエラーを報告し、そのフェーズを失敗として返します。

不明なプラグインステップ

次の順に確認します。

1. ローカルのリファレンスを確認します：devops-skills-plugin/skills/jenkinsfile-validator/references/common_plugins.md
2. Context7 を検索します。
   • mcp__context7__resolve-library-id を使い、jenkinsci <plugin-name>-plugin のようなクエリを指定します。
   • 使用方法とパラメーターについて、mcp__context7__query-docs を実行します。
3. Web でフォールバック検索します：plugins.jenkins.io と Jenkins の公式ドキュメント

オフライン／エアギャップ環境でのモード

• すべてのローカルバリデーターを実行します。
• プラグインのドキュメントを取得できない場合は、次のように報告します："Plugin docs lookup skipped due to environment constraints; local validation only."

プラグインドキュメントの検索ワークフロー

プラグイン固有の検証が求められた場合：

1. Jenkinsfile またはバリデーターのログから、不明なステップを特定します。
2. まず references/common_plugins.md を確認します。
3. 記載がない場合は、Context7（resolve-library-id、次に query-docs）を使用します。
4. それでも見つからない場合は、公式プラグインインデックス／ドキュメントを Web 検索します。
5. 必須パラメーター、オプションのパラメーター、バージョン依存の注意事項、セキュリティに関するガイダンスを返します。

リファレンス

ローカルリファレンス：

• devops-skills-plugin/skills/jenkinsfile-validator/references/declarative_syntax.md
• devops-skills-plugin/skills/jenkinsfile-validator/references/scripted_syntax.md
• devops-skills-plugin/skills/jenkinsfile-validator/references/best_practices.md
• devops-skills-plugin/skills/jenkinsfile-validator/references/common_plugins.md

外部リファレンス：

• Jenkins Pipeline Syntax
• Pipeline Development Tools
• Pipeline Best Practices
• Jenkins Plugins

レポートテンプレート

検証結果の報告では、次の構成を使用します。

Validation Target: <path>
Pipeline Type: <Declarative|Scripted|Shared Library|Unknown>

Findings:
- ERROR [Line X]: <issue>
- WARNING [Line Y]: <issue>
- INFO [Line Z]: <suggestion>

Phase Results:
- Syntax: <PASSED|FAILED|SKIPPED>
- Security: <PASSED|FAILED|SKIPPED>
- Best Practices: <PASSED|REVIEW NEEDED|SKIPPED>

Exit Code: <0|1|2>
Next Actions:
1. <highest-priority fix>
2. <second fix>

実行例

例 1：Jenkinsfile の完全な検証

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
bash "$SKILL_DIR/scripts/validate_jenkinsfile.sh" Jenkinsfile

想定される動作：

• 構文、セキュリティ、ベストプラクティスの各検証を実行します。
• 各フェーズの結果と統合サマリーを出力します。
• オーケストレーターのルールに従って 0/1/2 を返します。

例 2：共有ライブラリディレクトリの検証

SKILL_DIR="devops-skills-plugin/skills/jenkinsfile-validator"
bash "$SKILL_DIR/scripts/validate_shared_library.sh" examples/shared-library

想定される動作：

• vars/ と src/ の両方のファイルを検証します。
• 行番号を含む問題を集約します。
• エラーがある場合は 1 を返します。

例 3：不明なプラグインステップのフォローアップ

入力ステップ：

nexusArtifactUploader artifacts: [[...]], nexusUrl: 'https://nexus.example.com'

手順：

1. まずローカルで検証します。
2. ステップの動作が不明確な場合は、Context7 を使ってドキュメントを解決します。
3. 利用できない場合は、プラグインサイトのドキュメントを使用します。
4. 使用方法のガイダンスと、セキュリティに配慮したパラメーターパターンを報告します。

完了条件

次のすべてを満たした場合、スキルの利用は完了です。

• コマンドでは正規化されたパス（$SKILL_DIR/scripts/...）を使用し、作業ディレクトリの曖昧さがありません。
• 前提条件とオプションの依存関係が明示されています。
• 終了コードの意味とログの重要度の解釈が文書化されています。
• 不足しているツール／ドキュメントや制約のある環境でのフォールバック動作が定義されています。
• 完全な検証と共有ライブラリの検証について、少なくとも 1 つずつ実行可能な例があります。
• レポート形式が決定論的で、実用的です。