gitlab-ci-validator

GitLab CI/CD バリデーター

.gitlab-ci.yml の設定を検証、リント、テストし、セキュリティを確保するための包括的なツールキットです。

トリガーフレーズ

次のような意図を含むリクエストには、このスキルを使用してください。

• 「この .gitlab-ci.yml を検証して」
• 「この GitLab パイプラインが失敗するのはなぜですか？」
• 「GitLab CI のセキュリティレビューを実施して」
• 「パイプラインのベストプラクティスを確認して」
• 「マージ前に GitLab CI の設定をリントして」

セットアップと前提条件（最初に実行）

以下のコマンドはすべて、現在の作業ディレクトリがリポジトリのルートであることを前提としています。

# Ensure validator scripts are executable
chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.py

# Required runtime
python3 --version

オーケストレーションには、次の正規コマンドパスを使用します。

VALIDATOR="bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh"

ローカル実行ツール（--test-only 用、任意）：

bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/install_tools.sh

クイックスタートコマンド

# 1) Full validation (syntax + best practices + security)
$VALIDATOR .gitlab-ci.yml

# 2) Syntax and schema only (required first gate)
$VALIDATOR .gitlab-ci.yml --syntax-only

# 3) Best-practices only (recommended)
$VALIDATOR .gitlab-ci.yml --best-practices

# 4) Security only (required before merge)
$VALIDATOR .gitlab-ci.yml --security-only

# 5) Optional local pipeline structure test (needs gitlab-ci-local + Docker)
$VALIDATOR .gitlab-ci.yml --test-only

# 6) Strict mode (treat best-practice warnings as failure)
$VALIDATOR .gitlab-ci.yml --strict

決定論的な検証ワークフロー

次のゲートを順番に実行してください。

1. クイックスタートコマンド 2（--syntax-only）を実行します。
2. 構文エラーがある場合は、続行する前に停止してエラーを修正します。
3. クイックスタートコマンド 3（--best-practices）を実行し、該当する改善を適用します。
4. クイックスタートコマンド 4（--security-only）を実行し、マージ前に critical／high の検出事項をすべて修正します。
5. 任意でクイックスタートコマンド 5（--test-only）を実行し、ローカル実行を確認します。
6. 最終的なマージゲートとして、クイックスタートコマンド 6（--strict）を実行します。

必須ゲート：構文＋セキュリティ。 推奨ゲート：ベストプラクティス。 任意ゲート：ローカル実行テスト。

ルールの重大度の根拠とドキュメントへのリンク

重大度モデル

• critical：認証情報／シークレットの直接的な漏えい、または侵害につながる可能性が高い経路です。マージをブロックします。
• high：悪用可能な危険な動作、または重大なセキュリティの後退です。マージ前に修正してください。
• medium：現実的なリスクを伴うセキュリティ強化の不足です。追跡し、早めに修正してください。
• low／suggestion：最適化または保守性の改善です。

ルールの分類と重要性

• 構文ルール（yaml-syntax、job-stage-undefined、dependencies-undefined-job）：パイプラインの解析エラーや依存関係の失敗を防ぎます。
• ベストプラクティスのルール（cache-missing、artifact-no-expiration、dag-optimization）：実行コストを削減し、パイプラインのスループットを向上させます。
• セキュリティルール（hardcoded-password、curl-pipe-bash、include-remote-unverified）：認証情報の漏えいやサプライチェーンのリスクを低減します。

参考資料

• ローカルの構文リファレンス：devops-skills-plugin/skills/gitlab-ci-validator/docs/gitlab-ci-reference.md
• ローカルのベストプラクティス：devops-skills-plugin/skills/gitlab-ci-validator/docs/best-practices.md
• ローカルの一般的な問題：devops-skills-plugin/skills/gitlab-ci-validator/docs/common-issues.md
• GitLab CI YAML リファレンス：https://docs.gitlab.com/ee/ci/yaml/
• GitLab CI/CD コンポーネント：https://docs.gitlab.com/ee/ci/components/
• GitLab パイプラインのセキュリティガイダンス：https://docs.gitlab.com/ee/ci/pipelines/settings.html

ツールまたは環境の制約への対処

• python3 がない場合：
  • 動作：バリデーターを実行できません。
  • 対処：Python 3 をインストールして、再実行してください。
• PyYAML がない場合：
  • 動作：可能であれば、python_wrapper.sh が .venv を自動作成し、pyyaml をインストールします。
  • 制限された環境／オフライン環境での対処：内部ミラーから pyyaml を事前にインストールしてから、再実行してください。
• gitlab-ci-local、node、または docker がない場合：
  • 動作：--test-only は警告または失敗を報告します。
  • 対処：ローカル実行テストをスキップし、構文／ベストプラクティス／セキュリティの各ゲートを続行してください。
• スクリプトに実行権限がない場合：
  • 動作：シェルで権限エラーが発生します。
  • 対処：セットアップのセクションにある chmod コマンドを再実行してください。

例

例 1：新しいパイプラインの検証

$VALIDATOR examples/basic-pipeline.gitlab-ci.yml --syntax-only
$VALIDATOR examples/basic-pipeline.gitlab-ci.yml --security-only

例 2：マージ前のハードゲート

$VALIDATOR .gitlab-ci.yml --strict

例 3：CI への統合

stages:
  - validate

validate_gitlab_ci:
  stage: validate
  script:
    - chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.sh devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.py
    - bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict

個別のバリデーター（上級者向け）

# Syntax validator (via wrapper for PyYAML fallback)
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_syntax.py .gitlab-ci.yml

# Best-practices validator
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/check_best_practices.py .gitlab-ci.yml

# Security validator
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/check_security.py .gitlab-ci.yml

完了基準

• Frontmatter の name と description が変更されていません。
• 正規のオーケストレーター経路が一貫して使用されています。
• セットアップと chmod の前提条件が、ワークフローや使用例より前に記載されています。
• クイックスタートとワークフローで内容が重複しておらず、ワークフローからクイックスタートのゲートを参照しています。
• 重大度の根拠と、ルールからドキュメントへの参照が明示されています。
• ツールが見つからない場合や、環境に制約がある場合のフォールバック動作が記載されています。
• 使用例をリポジトリのルートから実行できます。

注記

• このスキルは設定と静的パターンを検証しますが、本番パイプラインは実行しません。
• 実行時の動作を確認するには、gitlab-ci-local または GitLab CI Lint を使用してください。