gitlab-ci-generator

GitLab CI/CD パイプラインジェネレーター

概要

現在のベストプラクティス、セキュリティ標準、命名規則に従って、本番環境に対応した GitLab CI/CD パイプライン設定を生成します。生成されたすべてのリソースは、構文の正確性とベストプラクティスへの準拠を確認するため、devops-skills:gitlab-ci-validator スキルを使用して自動的に検証されます。

---

トリガーフレーズ

次のような GitLab CI/CD の生成をユーザーが依頼した場合は、このスキルを使用します。

• 「...用の .gitlab-ci.yml を作成して」
• 「Node/Python/Java 用の GitLab パイプラインを作成して」
• 「GitLab CI に Docker のビルドジョブとデプロイジョブを追加して」
• 「GitLab の親子パイプラインまたはマルチプロジェクトパイプラインを設定して」
• 「GitLab CI に SAST／依存関係スキャンのテンプレートを含めて」

実行モデル

次の決定論的なフローに順番に従います。

1. 依頼の複雑さ（targeted、lightweight、full）を分類します。
2. その複雑さに必要なリファレンス階層のみを読み込みます。
3. 選択したモードに対応する応答プロファイルを出力します。
4. パイプライン全体を生成する場合は、最も近いテンプレートを基にカスタマイズします。
5. パイプライン全体を生成した場合は、Critical／High の厳格なゲートで検証します。
6. 検証ステータスとテンプレート／バージョンに関する注記を添えて出力を提示します。

ツールを利用できない場合は、文書化されたフォールバックの手順を使用し、その旨を明示します。

モードの振り分け（簡易判断）

依頼の内容	モード	必要なリファレンス	出力プロファイル
一般的なジョブ／ステージを使った、リスクの低いシンプルな単一ファイルのパイプライン	Lightweight	Tier 1（必要な場合のみ Tier 2 も参照）	簡易確認＋簡潔な最終セクション
複数環境へのデプロイ、高度な rules、include／テンプレート、セキュリティ／コンプライアンスに関わるワークフロー、または不明確でリスクのある要件	Full	Tier 1＋Tier 2（必要な場合のみ Tier 3 も参照）	詳細確認＋すべての最終セクション
レビュー／Q&A／コードスニペット／重点的な修正（ファイル全体の生成ではないもの）	Targeted	直接関連するファイルのみ	簡潔で対象を絞った回答（定型文全体は含めない）

パイプライン全体の生成依頼について判断に迷う場合は、Full モードを選択します。

生成前に必ず行う手順

重要： GitLab CI/CD パイプライン全体を生成する前に、必ず次の手順を完了してください。

ステップ 1：複雑さを分類する（必須）

モード	適用するケース	最低限の確認
Targeted	パイプライン全体の生成を求めていない、レビュー／Q&A／コードスニペット／重点的な修正	簡潔で対象を絞った回答
Lightweight	シンプルな単一ファイルのパイプライン、一般的なステージ／ジョブ、高度な GitLab 機能を使わず、機密性の高いデプロイ／セキュリティのカスタマイズもないもの	簡易確認
Full	複数環境へのデプロイ、include／テンプレート、高度な rules のロジック、セキュリティスキャンのカスタマイズ、コンプライアンスに関わるワークフロー、または不明確でリスクのある依頼	詳細確認

パイプライン全体の生成依頼について判断に迷う場合は、既定で Full モードを選択します。

ステップ 2：階層に応じてリファレンスを読み込む（必須）

選択したモードに応じて、オープン／読み取りアクションを使用してリファレンスを読み込みます。

ターゲットモード（レビュー／Q&A／スニペット／対象を絞った修正）：

• 対象を絞ったリクエストに直接関連するリファレンス／テンプレートのみを読み込みます。
• フル生成の階層 1／階層 2 のチェック項目は適用しません。

階層 1（Lightweight モードと Full モードで完全なパイプラインを生成する場合に必須）：

1. references/best-practices.md - セキュリティ、パフォーマンス、命名の基本
2. references/common-patterns.md - 開始時のパターン選択
3. assets/templates/ 内の該当するテンプレート：
   • Docker パイプライン → assets/templates/docker-build.yml
   • Kubernetes デプロイ → assets/templates/kubernetes-deploy.yml
   • 複数プロジェクトのパイプライン → assets/templates/multi-project.yml
   • 基本パイプライン → assets/templates/basic-pipeline.yml

階層 2（Full モードでは必須、Lightweight モードでは任意）：

1. references/gitlab-ci-reference.md - キーワード／構文のエッジケース
2. references/security-guidelines.md - セキュリティに関わる制御

階層 3（外部ドキュメントの参照が条件付きで必要）：

• ローカルのリファレンスでは、リクエストされた機能やバージョン固有の動作をカバーできない場合にのみ使用します。
• 「GitLab CI/CD Documentation Lookup」の検索フローに従います。

必須のローカルリファレンスまたはテンプレートが利用できない場合：

• 不足しているパスを正確に報告します。
• 利用可能なリファレンスを使って続行し、前提を明示します。
• 不足している重要な入力が解決されるまでは、本番環境ですぐに使えるという確信を示さないでください。

ステップ 3：理解を確認する（明示的な出力が必須）

Lightweight 確認モード

簡単なリクエストにのみ使用します。

必須の形式：

## Reference Analysis Complete (Lightweight)

**Pattern:** [Pattern name] from common-patterns.md
**Template:** [Template file]
**Key standards to enforce:**
- [2-3 concrete standards]

例：

## Reference Analysis Complete (Lightweight)

**Pattern:** Basic Build-Test-Deploy from common-patterns.md
**Template:** assets/templates/basic-pipeline.yml
**Key standards to enforce:**
- Pin runtime image versions (no `:latest`)
- Add explicit job timeouts
- Use `rules` instead of deprecated `only`/`except`

Full 確認モード

複雑なリクエストやセキュリティに関わるリクエストに使用します。

必須の形式：

## Reference Analysis Complete (Full)

**Pipeline Pattern Identified:** [Pattern name] from common-patterns.md
- [Brief description of why this pattern fits]

**Best Practices to Apply:**
- [List 3-5 key best practices relevant to this pipeline]

**Security Guidelines:**
- [List security measures to implement]

**Template Foundation:** [Template file name]
- [What will be customized from this template]

例：

## Reference Analysis Complete (Full)

**Pipeline Pattern Identified:** Docker Build + Kubernetes Deployment from common-patterns.md
- User needs containerized deployment to K8s clusters with staging/production environments

**Best Practices to Apply:**
- Pin all Docker images to specific versions (not `:latest`)
- Use caching for pip dependencies
- Implement DAG optimization with `needs` keyword
- Set explicit timeout on all jobs (15-20 minutes)
- Use `resource_group` for deployment jobs

**Security Guidelines:**
- Use masked CI/CD variables for secrets (KUBE_CONTEXT, registry credentials)
- Include container scanning with Trivy
- Never expose secrets in logs

**Template Foundation:** assets/templates/docker-build.yml + assets/templates/kubernetes-deploy.yml
- Combine Docker build pattern with K8s kubectl deployment
- Add Python-specific test jobs

完全なパイプラインを生成する場合、確認を省略することはできません。

---

主な機能

1. 基本的な CI/CD パイプラインを生成する

適切な構成、セキュリティのベストプラクティス、効率的な CI/CD パターンを備えた、完全で本番環境に対応した .gitlab-ci.yml ファイルを作成します。

使用する場面：

• ユーザーからのリクエスト：「〜向けの GitLab パイプラインを作成して」「CI/CD パイプラインを構築して」「GitLab CI 設定を生成して」
• シナリオ：CI/CD パイプライン、自動テスト、ビルドの自動化、デプロイパイプライン

手順：

1. ユーザーの要件（自動化する内容）を把握します
2. ステージ、ジョブ、依存関係、アーティファクトを特定します
3. 構造の基盤として assets/templates/basic-pipeline.yml を使用します
4. 実装パターンについては references/best-practices.md を参照します
5. 標準的なパイプラインパターンについては references/common-patterns.md を参照します
6. 次の原則に従ってパイプラインを生成します：
   • 意味が明確なステージ名とジョブ名を使用します
   • Docker イメージは :latest ではなく特定のバージョンに固定します
   • マスクされた変数を使って、適切なシークレット管理を実装します
   • 依存関係をキャッシュしてパフォーマンスを向上させます
   • 有効期限を設定し、アーティファクトを適切に処理します
   • 適切な場合は needs キーワードを使用して DAG を最適化します
   • retry と allow_failure を使用して適切なエラー処理を追加します
   • 非推奨の only／except ではなく rules を使用します
   • すべてのジョブに timeout を明示的に設定します（通常は 10～30 分）
   • コメントでジョブの説明をわかりやすく記述します
7. devops-skills:gitlab-ci-validator スキルを使用して、生成したパイプラインを必ず検証します
8. 検証に失敗した場合は問題を修正し、再検証します

構成例：

# Basic CI/CD Pipeline
# Builds, tests, and deploys the application

stages:
  - build
  - test
  - deploy

# Global variables
variables:
  NODE_VERSION: "20"
  DOCKER_DRIVER: overlay2

# Default settings for all jobs
default:
  image: node:20-alpine
  timeout: 20 minutes  # Default timeout for all jobs
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  before_script:
    - echo "Starting job ${CI_JOB_NAME}"
  tags:
    - docker
  interruptible: true

# Build stage - Compiles the application
build-application:
  stage: build
  timeout: 15 minutes
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  rules:
    - changes:
        - src/**/*
        - package*.json
      when: always
    - when: on_success

# Test stage
test-unit:
  stage: test
  needs: [build-application]
  script:
    - npm run test:unit
  coverage: '/Coverage: \d+\.\d+%/'
  artifacts:
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

test-lint:
  stage: test
  needs: []  # Can run immediately
  script:
    - npm run lint
  allow_failure: true

# Deploy stage
deploy-staging:
  stage: deploy
  needs: [build-application, test-unit]
  script:
    - npm run deploy:staging
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
  when: manual

deploy-production:
  stage: deploy
  needs: [build-application, test-unit]
  script:
    - npm run deploy:production
  environment:
    name: production
    url: https://example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manual
  resource_group: production

2. Docker ビルドパイプラインを生成する

Docker イメージをビルド、テストし、コンテナレジストリにプッシュするパイプラインを作成します。

使用する場面：

• ユーザーのリクエスト：「Docker ビルドパイプラインを作成して…」「Docker イメージをビルドしてプッシュして…」
• シナリオ：コンテナのビルド、マルチステージ Docker ビルド、レジストリへのプッシュ

プロセス：

1. Docker ビルドの要件（ベースイメージ、レジストリ、タグ）を把握します
2. assets/templates/docker-build.yml をベースとして使用します
3. ビルドに Docker-in-Docker または Kaniko を実装します
4. レジストリ認証を設定します
5. イメージのタグ付け戦略を実装します
6. 必要に応じてセキュリティスキャンを追加します
7. devops-skills:gitlab-ci-validator スキルを使用して、必ず検証します

例：

stages:
  - build
  - scan
  - push

variables:
  DOCKER_DRIVER: overlay2
  IMAGE_NAME: $CI_REGISTRY_IMAGE
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

# Build Docker image
docker-build:
  stage: build
  image: docker:24-dind
  timeout: 20 minutes
  services:
    - docker:24-dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build
        --cache-from $IMAGE_NAME:latest
        --tag $IMAGE_NAME:$IMAGE_TAG
        --tag $IMAGE_NAME:latest
        .
    - docker push $IMAGE_NAME:$IMAGE_TAG
    - docker push $IMAGE_NAME:latest
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  retry:
    max: 2
    when:
      - runner_system_failure

# Scan for vulnerabilities
container-scan:
  stage: scan
  image: aquasec/trivy:0.49.0
  timeout: 15 minutes
  script:
    - trivy image --exit-code 0 --severity HIGH,CRITICAL $IMAGE_NAME:$IMAGE_TAG
  needs: [docker-build]
  allow_failure: true
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

3. Kubernetes デプロイパイプラインを生成する

アプリケーションを Kubernetes クラスターにデプロイするパイプラインを作成します。

使用する場面：

• ユーザーのリクエスト：「Kubernetes にデプロイして…」「K8s デプロイパイプラインを作成して…」
• シナリオ：Kubernetes デプロイ、Helm デプロイ、kubectl 操作

プロセス：

1. Kubernetes のデプロイ方法（kubectl、Helm、Kustomize）を特定します
2. assets/templates/kubernetes-deploy.yml をベースとして使用します
3. クラスター認証（サービスアカウント、kubeconfig）を設定します
4. 適切な環境管理を実装します
5. ロールバック機能を追加します
6. devops-skills:gitlab-ci-validator スキルを使用して、必ず検証します

例：

stages:
  - build
  - deploy

# Kubernetes deployment job
deploy-k8s:
  stage: deploy
  image: bitnami/kubectl:1.29
  timeout: 10 minutes
  before_script:
    - kubectl config use-context $KUBE_CONTEXT
  script:
    - kubectl set image deployment/myapp myapp=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA -n $KUBE_NAMESPACE
    - kubectl rollout status deployment/myapp -n $KUBE_NAMESPACE --timeout=5m
  environment:
    name: production
    url: https://example.com
    kubernetes:
      namespace: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  resource_group: k8s-production
  retry:
    max: 2
    when:
      - runner_system_failure

4. マルチプロジェクトパイプラインを生成する

他のプロジェクトをトリガーするパイプライン、または親子パイプラインパターンを使用するパイプラインを作成します。

使用する場面：

• ユーザーのリクエスト：「マルチプロジェクトパイプラインを作成して…」「他のパイプラインをトリガーして…」
• シナリオ：モノレポ、マイクロサービス、オーケストレーションパイプライン

プロセス：

1. パイプラインのオーケストレーション要件を特定します
2. assets/templates/multi-project.yml または親子テンプレートを使用します
3. 適切なアーティファクトの受け渡しを設定します
4. 適切な場合は並列実行を実装します
5. devops-skills:gitlab-ci-validator スキルを使用して、必ず検証します

例（親子）：

# Parent pipeline
stages:
  - trigger

generate-child-pipeline:
  stage: trigger
  script:
    - echo "Generating child pipeline config"
    - |
      cat > child-pipeline.yml <<EOF
      stages:
        - build

      child-job:
        stage: build
        script:
          - echo "Running child job"
      EOF
  artifacts:
    paths:
      - child-pipeline.yml

trigger-child:
  stage: trigger
  trigger:
    include:
      - artifact: child-pipeline.yml
        job: generate-child-pipeline
    strategy: depend
  needs: [generate-child-pipeline]

5. テンプレートベースの設定を生成する

extends、YAML アンカー、include を使用して再利用可能なテンプレートを作成します。

使用する場面：

• ユーザーのリクエスト：「再利用可能なテンプレートを作成して…」「モジュール式のパイプライン設定を構築して…」
• シナリオ：テンプレートライブラリ、DRY な設定、共有 CI/CD ロジック

プロセス：

1. 抽出する共通パターンを特定します
2. 非表示ジョブ（. で始まるジョブ）を作成します
3. 継承には extends キーワードを使用します
4. include を使って個別のファイルに整理します
5. devops-skills:gitlab-ci-validator スキルを使用して、必ず検証します

例：

# Hidden template jobs (include timeout in templates)
.node-template:
  image: node:20-alpine
  timeout: 15 minutes  # Default timeout for jobs using this template
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  before_script:
    - npm ci
  interruptible: true

.deploy-template:
  timeout: 10 minutes  # Deploy jobs should have explicit timeout
  before_script:
    - echo "Deploying to ${ENVIRONMENT}"
  after_script:
    - echo "Deployment complete"
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
  interruptible: false  # Deploys should not be interrupted

# Actual jobs using templates
build:
  extends: .node-template
  stage: build
  script:
    - npm run build

deploy-staging:
  extends: .deploy-template
  stage: deploy
  variables:
    ENVIRONMENT: staging
  script:
    - ./deploy.sh staging
  resource_group: staging

6. GitLab CI/CD のドキュメントを参照する方法

ローカルのリファレンスで、求められている機能やバージョンに依存する動作を確認できない場合にのみ、このフローを使用します。

検出：

• ユーザーが GitLab の特定の機能（例：「Auto DevOps」、「SAST」、「dependency scanning」）に言及している
• ユーザーが GitLab テンプレートとの統合を求めている
• パイプラインで特定の GitLab ランナー機能が必要である

手順：

1. 機能を特定します：

   • GitLab の機能名またはテンプレート名を抽出します
   • バージョン固有の情報が必要かどうかを判断します

2. まずローカルのリファレンスを確認します（Tier 1/Tier 2）：

   • references/common-patterns.md
   • references/gitlab-ci-reference.md
   • references/security-guidelines.md

3. 外部参照が必要な場合は、まず Context7 を使用します：

   • ライブラリを解決します：mcp__context7__resolve-library-id
   • ドキュメントを検索します：mcp__context7__query-docs
   • 二次情報源よりも GitLab の公式ドキュメント／ライブラリを優先します

4. Context7 を利用できない場合、または情報が不十分な場合は、ウェブ検索に切り替えます：

   • web.search_query を使用します
   • 検索パターン：「GitLab CI/CD [feature] documentation」
   • docs.gitlab.com の検索結果を優先します

5. 必要に応じて、特定のドキュメントページを開いて情報を抽出します：

   • 選択したドキュメントページには web.open を使用します
   • 必要な構文、変数、バージョン制約を記録します

6. 見つかったドキュメントを次の点について分析します：

   • 現在推奨されている方法
   • 必要な変数と設定
   • テンプレートの include 構文
   • ベストプラクティスとセキュリティに関する推奨事項
   • 使用例

7. ネットワークツールを利用できない場合（オフライン／制限環境）：

   • ローカルのリファレンスのみを使用します
   • 外部でバージョンを確認できなかったことを明記します
   • 最終出力にバージョンに関する前提を記載します

8. 見つかった情報をもとにパイプラインを生成します：

   • 正しいテンプレートの include 構文を使用します
   • 必要な変数を設定します
   • セキュリティのベストプラクティスを追加します
   • バージョンと選択内容に関するコメントを含めます

GitLab テンプレートの使用例：

# Include GitLab's security templates (use Jobs/ prefix for current templates)
include:
  - template: Jobs/SAST.gitlab-ci.yml
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml

# Customize SAST behavior via global variables
# Note: Set variables globally rather than overriding template jobs
# to avoid validation issues with partial job definitions
variables:
  SAST_EXCLUDED_PATHS: "spec, test, tests, tmp, node_modules"
  DS_EXCLUDED_PATHS: "node_modules, vendor"
  SECURE_LOG_LEVEL: "info"

重要： GitLab テンプレートで include を使用する場合、含められるジョブは テンプレート内で完全に定義されています。カスタマイズする必要がある場合は、 ジョブの一部だけをオーバーライドする設定を作成するのではなく、グローバルに 変数を設定してください（バリデーターが含められたテンプレートを解決できないため、 ローカル検証に失敗します）。GitLab は実行時に設定をマージしますが、 ローカルバリデーターが参照できるのは .gitlab-ci.yml ファイルのみです。

検証ワークフロー

重要： 生成した GitLab CI/CD 設定は、ユーザーに提示する前に必ず検証する必要があります。

検証プロセス

1. 主な検証方法： 完全なパイプラインを生成した後、devops-skills:gitlab-ci-validator スキルを実行します。

   Skill: devops-skills:gitlab-ci-validator
   

2. スクリプトによる代替方法（バリデータースキルを実行できない場合）：

   PIPELINE_FILE="<generated-output-path>"
   

   • PIPELINE_FILE に生成したファイルの正確なパスを設定します（例：pipelines/review.yml または .gitlab-ci.yml）。
   • ファイルが存在しない場合は、直ちに処理を失敗させます。

     if [[ ! -f "$PIPELINE_FILE" ]]; then
       echo "ERROR: CI file not found: $PIPELINE_FILE" >&2
       exit 1
     fi
     

   # From repository root
   bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh "$PIPELINE_FILE"
   

   # From skills/gitlab-ci-generator directory
   bash ../gitlab-ci-validator/scripts/validate_gitlab_ci.sh "$PIPELINE_FILE"
   

   • スクリプトに実行権限がない場合：

     chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh
     

   • GitLab プロジェクトのコンテキストを利用できる場合は、API によるリントを代替手段として利用できます（任意）。

     jq --null-input --arg yaml "$(<"$PIPELINE_FILE")" '.content=$yaml' \
     | curl --header "Content-Type: application/json" \
       --url "https://gitlab.com/api/v4/projects/:id/ci/lint?include_merged_yaml=true" \
       --data @-
     

3. 手動による代替方法（主な方法とスクリプトによる方法の両方が利用できない場合のみ）：

   • YAML の妥当性、ステージ／ジョブの参照、明らかなシークレットの露出について手動で確認します。
   • 出力に Validation status: Manual fallback (not fully verified) と記載します。
   • 重大または高リスクを確実に排除できない場合は、本番環境で利用可能だと主張しないでください。

4. バリデータースキル／スクリプトの確認項目：

   • YAML 構文の妥当性を検証する
   • GitLab CI/CD スキーマへの準拠を確認する
   • ジョブの参照と依存関係を検証する
   • ベストプラクティスへの違反を確認する
   • セキュリティスキャンを実施する
   • エラー、警告、問題を報告する

5. 検証結果を分析し、重大度に応じて対応します。

   重大度	必要な対応
   CRITICAL	提示する前に必ず修正してください。パイプラインが機能しない、または深刻なセキュリティ上の問題があります。
   HIGH	提示する前に必ず修正してください。セキュリティまたは機能に重大な問題があります。
   MEDIUM	提示する前に修正してください。修正するか、該当しない理由を説明してください。
   LOW	修正するか、問題として認識した旨を伝えてください。推奨事項をユーザーに知らせます。
   SUGGESTIONS	内容を確認し、有益であれば適用してください。修正は必須ではありません。

6. 修正と再検証のループ（重大または高リスクの問題がある場合は必須）：

   While validation has CRITICAL or HIGH issues:
     1. Edit the generated file to fix the issue
     2. Re-run validation
     3. Repeat until no CRITICAL or HIGH issues remain
   

7. ユーザーに提示する前に、次の点を確認します。

   • 重大な問題がゼロである
   • 高リスクの問題がゼロである
   • 中リスクの問題が修正済み、または許容できる理由が説明されている
   • 低リスクの問題と提案について、認識した旨が示されている

8. 検証済みの設定を提示する際は、次の内容を記載します。

   • 検証状況を明確に示す
   • 使用した検証方法（スキル、スクリプトによる代替、手動による代替）を示す
   • 残っている中リスク／低リスクの問題と、その説明を列挙する
   • テンプレート／バージョンの最新性に関する注記を含める
   • 使用方法を説明する
   • 選択したトレードオフに触れる

本番環境で利用可能だと主張する場合、重大／高リスクのゲートを厳守する必要があります。例外は認められません。

検証の合格基準

次の場合、パイプラインは提示可能です。

• ✅ 検証方法を実行済み（バリデータースキルまたはスクリプトによる代替）
• ✅ 構文検証：合格
• ✅ セキュリティスキャン：重大または高リスクの問題なし
• ✅ ベストプラクティス：確認済み（説明があれば警告は許容されます）

次の場合、パイプラインは提示できません。

• ❌ 構文エラーがある
• ❌ 重大なセキュリティ上の問題がある
• ❌ 高リスクのセキュリティ上の問題がある
• ❌ ジョブの参照が壊れている
• ❌ 手動による代替方法のみを使用し、重大／高リスクを排除できない

検証を省略する場合

次の場合に限り、検証を省略できます。

• 部分的なコードスニペットを生成する場合（完全なファイルではない）
• ドキュメント用の例を作成する場合
• ユーザーが検証の省略を明示的に依頼した場合

MEDIUM 重大度の問題への対応（出力必須）

バリデーターが MEDIUM 重大度の問題を報告した場合、必ず修正するか、許容できる理由を説明してください。この説明は出力に必須です。

MEDIUM の問題に対応する際の必須フォーマット：

## Validation Issues Addressed

### MEDIUM Severity Issues

| Issue | Status | Explanation |
|-------|--------|-------------|
| [Issue code] | Fixed/Acceptable | [Why it was fixed OR why it's acceptable] |

MEDIUM の問題に関する説明の例：

## Validation Issues Addressed

### MEDIUM Severity Issues

| Issue | Status | Explanation |
|-------|--------|-------------|
| `image-variable-no-digest` | Acceptable | Using `python:${PYTHON_VERSION}-alpine` allows flexible version management via CI/CD variables. The PYTHON_VERSION variable is controlled internally and pinned to "3.12". SHA digest pinning would require updating the digest with every image update, adding maintenance burden without significant security benefit for this use case. |
| `pip-without-hashes` | Acceptable | This pipeline installs well-known packages (pytest, flake8) from PyPI. Using `--require-hashes` would require maintaining hash files for all transitive dependencies. For internal CI/CD, the security trade-off is acceptable. For higher security environments, consider using a private PyPI mirror with verified packages. |
| `git-strategy-none` | Acceptable | The `stop-staging` and `rollback-production` jobs use `GIT_STRATEGY: none` because they only run kubectl commands that don't require source code. The scripts are inline in the YAML (not from the repo), so there's no risk of executing untrusted code. |

修正する場合と許容する場合の判断基準：

シナリオ	対応
本番環境／高セキュリティ環境	問題を修正する
簡単に修正でき、デメリットがない問題	問題を修正する
修正によって複雑さが大幅に増す	説明を添えて許容する
修正に外部の変更（例：CI/CD 変数）が必要	説明を添えて許容する
このコンテキストでは誤検知である問題	説明を添えて許容する

提案の確認（出力必須）

バリデーターが提案を提示した場合、必ず簡潔に言及し、適用すべきかどうかを説明してください。

必須フォーマット：

## Validator Suggestions Review

| Suggestion | Recommendation | Reason |
|------------|----------------|--------|
| [suggestion] | Apply/Skip | [Why] |

提案の確認例：

## Validator Suggestions Review

| Suggestion | Recommendation | Reason |
|------------|----------------|--------|
| `missing-retry` on test jobs | Skip | Test jobs are deterministic and don't interact with external services. Retry would mask flaky tests rather than fail fast. |
| `parallel-opportunity` for test-unit | Apply if beneficial | Could be added if pytest supports sharding. Add `parallel: 3` with `pytest --shard=${CI_NODE_INDEX}/${CI_NODE_TOTAL}` if test suite is large enough to benefit. |
| `dag-optimization` for stop-staging | Skip | This job is manual and only runs on environment cleanup. DAG optimization wouldn't provide meaningful speedup. |
| `no-dependency-proxy` | Apply for production | Consider using `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` to avoid Docker Hub rate limits. Requires GitLab Premium. |
| `environment-no-url` for rollback | Skip | Rollback jobs don't deploy new versions, so a URL would be misleading. |
| `missing-coverage` for lint job | Skip | Linting doesn't produce coverage data. This is a false positive. |

テンプレートとバージョンに関する注記（出力必須）

検証結果の後に、テンプレートとドキュメントに関する前提の新しさについて、簡潔な注記を含めてください。

必須フォーマット：

## Template and Version Notes

- **Template base:** [assets/templates/<file>.yml]
- **Template customization scope:** [what changed from template]
- **Version/doc basis:** [Context7, docs.gitlab.com, or local references only]
- **Freshness note:** [exact date checked, or "external lookup unavailable"]
- **Version-sensitive assumptions:** [if any]

例：

## Template and Version Notes

- **Template base:** assets/templates/docker-build.yml
- **Template customization scope:** Added unit-test stage and environment-specific deploy rules
- **Version/doc basis:** docs.gitlab.com include-template docs + local references
- **Freshness note:** Verified template syntax on 2026-02-28
- **Version-sensitive assumptions:** Uses `Jobs/SAST.gitlab-ci.yml` template path

使用手順のテンプレート（出力必須）

検証済みのパイプラインを提示した後、必ず使用手順を提示してください。これは省略できません。

必須フォーマット：

## Usage Instructions

### Required CI/CD Variables

Configure these variables in **Settings → CI/CD → Variables**:

| Variable | Description | Masked | Protected |
|----------|-------------|--------|-----------|
| [VARIABLE_NAME] | [Description] | Yes/No | Yes/No |

### Setup Steps

1. [First setup step]
2. [Second setup step]
...

### Pipeline Behavior

- **On push to `develop`:** [What happens]
- **On push to `main`:** [What happens]
- **On tag `vX.Y.Z`:** [What happens]

### Customization

[Any customization notes]

使用手順の例：

## Usage Instructions

### Required CI/CD Variables

Configure these variables in **Settings → CI/CD → Variables**:

| Variable | Description | Masked | Protected |
|----------|-------------|--------|-----------|
| `KUBE_CONTEXT` | Kubernetes cluster context name | No | Yes |
| `KUBE_NAMESPACE_STAGING` | Staging namespace (default: staging) | No | No |
| `KUBE_NAMESPACE_PRODUCTION` | Production namespace (default: production) | No | Yes |

**Note:** `CI_REGISTRY_USER`, `CI_REGISTRY_PASSWORD`, and `CI_REGISTRY` are automatically provided by GitLab.

### Kubernetes Integration Setup

1. **Enable Kubernetes integration** in **Settings → Infrastructure → Kubernetes clusters**
2. **Add your cluster** using the agent-based or certificate-based method
3. **Create namespaces** for staging and production if they don't exist:
   ```bash
   kubectl create namespace staging
   kubectl create namespace production

4. パイプラインを実行する前に、対象の名前空間にデプロイメントが存在することを確認してください

パイプラインの動作

• develop へのプッシュ時： テストを実行 → Docker イメージをビルド → ステージングに自動デプロイ
• main へのプッシュ時： テストを実行 → Docker イメージをビルド → 本番環境への手動デプロイ
• タグ vX.Y.Z の作成時： テストを実行 → Docker イメージをビルド → 本番環境への手動デプロイ

カスタマイズ

• APP_NAME 変数を、Kubernetes のデプロイメント名に合わせて更新します
• deploy-staging ジョブと deploy-production ジョブの環境 URL を変更します
• テンプレート内の Helm ジョブのコメントを解除して、Helm デプロイを追加します

## Best Practices to Enforce

Reference `references/best-practices.md` for comprehensive guidelines. Key principles:

### Mandatory Standards

1. **Security First:**
   - Pin Docker images to specific versions (not :latest)
   - Use masked variables for secrets ($CI_REGISTRY_PASSWORD should be masked)
   - Never expose secrets in logs
   - Validate inputs and sanitize variables
   - Use protected variables for sensitive environments

2. **Performance:**
   - Implement caching for dependencies (ALWAYS for npm, pip, maven, etc.)
   - Use `needs` keyword for DAG optimization (ALWAYS when jobs have dependencies)
   - Set artifact expiration to avoid storage bloat (ALWAYS set `expire_in`)
   - Use `parallel` execution *when applicable* (only if test framework supports sharding)
   - Minimize unnecessary artifact passing (use `artifacts: false` in `needs` when not needed)

3. **Reliability:**
   - **Set explicit `timeout` for ALL jobs** (prevents hanging jobs, typically 10-30 minutes)
     - Even when using `default` or `extends` for timeout inheritance, add explicit `timeout` to each job
     - This improves readability and avoids validator warnings about missing timeout
     - Example: A job using `.deploy-template` should still have `timeout: 15 minutes` explicitly set
   - Add retry logic for flaky operations (network calls, external API interactions)
   - Use `allow_failure` appropriately for non-critical jobs (linting, optional scans)
   - Use `resource_group` for deployment jobs (prevents concurrent deployments)
   - Add `interruptible: true` for test jobs (allows cancellation when new commits push)

4. **Naming:**
   - Job names: Descriptive, kebab-case (e.g., "build-application", "test-unit")
   - Stage names: Short, clear (e.g., "build", "test", "deploy")
   - Variable names: UPPER_SNAKE_CASE for environment variables
   - Environment names: lowercase (e.g., "production", "staging")

5. **Configuration Organization:**
   - Use `extends` for reusable configuration (PREFERRED over YAML anchors for GitLab CI)
   - Use `include` for modular pipeline files (organize large pipelines into multiple files)
   - Use `rules` instead of deprecated only/except (ALWAYS)
   - Define `default` settings for common configurations (image, timeout, cache, tags)
   - Use YAML anchors *only when necessary* for complex repeated structures within a single file
     - Note: `extends` is preferred because it provides better visualization in GitLab UI

6. **Error Handling:**
   - Set appropriate timeout values (ALWAYS - prevents hanging jobs)
   - Configure retry behavior for flaky operations (network calls, external APIs)
   - Use `allow_failure: true` for non-blocking jobs (linting, optional scans)
   - Add cleanup steps with `after_script` *when needed* (e.g., stopping test containers, cleanup)
   - Implement notification mechanisms *when required* (e.g., Slack integration for deployment failures)

## Resources

### References (Tiered Loading)

- `references/best-practices.md` (**Tier 1: required for all**) - Comprehensive GitLab CI/CD best practices
  - Security patterns, performance optimization
  - Pipeline design, configuration organization
  - Common patterns and anti-patterns
  - **Use this:** When implementing any GitLab CI/CD resource

- `references/common-patterns.md` (**Tier 1: required for all**) - Frequently used pipeline patterns
  - Basic CI pipeline patterns
  - Docker build and push patterns
  - Deployment patterns (K8s, cloud platforms)
  - Multi-project and parent-child patterns
  - **Use this:** When selecting which pattern to use

- `references/gitlab-ci-reference.md` (**Tier 2: required for Full mode**) - GitLab CI/CD YAML syntax reference
  - Complete keyword reference
  - Job configuration options
  - Rules and conditional execution
  - Variables and environments
  - **Use this:** For syntax and keyword details

- `references/security-guidelines.md` (**Tier 2: required for Full mode**) - Security best practices
  - Secrets management
  - Image security
  - Script security
  - Artifact security
  - **Use this:** For security-sensitive configurations

### Assets (Templates to Customize)

- `assets/templates/basic-pipeline.yml` - Complete basic pipeline template
- `assets/templates/docker-build.yml` - Docker build pipeline template
- `assets/templates/kubernetes-deploy.yml` - Kubernetes deployment template
- `assets/templates/multi-project.yml` - Multi-project orchestration template

**How to use templates:**
1. Copy the relevant template structure
2. Replace all `[PLACEHOLDERS]` with actual values
3. Customize logic based on user requirements
4. Remove unnecessary sections
5. Validate the result

## Typical Workflow Example

**User request:** "Create a CI/CD pipeline for a Node.js app with testing and Docker deployment"

**Process:**
1. ✅ Understand requirements:
   - Node.js application
   - Run tests (unit, lint)
   - Build Docker image
   - Deploy to container registry
   - Trigger on push and merge requests

2. ✅ Reference resources:
   - Check `references/best-practices.md` for pipeline structure
   - Check `references/common-patterns.md` for Node.js + Docker pattern
   - Use `assets/templates/docker-build.yml` as base

3. ✅ Generate pipeline:
   - Define stages (build, test, dockerize, deploy)
   - Create build job with caching
   - Create test jobs (unit, lint) with needs optimization
   - Create Docker build job
   - Add proper artifact management
   - Pin Docker images to versions
   - Include proper secrets handling

4. ✅ Validate:
   - Invoke `devops-skills:gitlab-ci-validator` skill
   - Fix any reported issues
   - Re-validate if needed

5. ✅ Present to user:
   - Show validated pipeline
   - Explain key sections
   - Provide usage instructions
   - Mention successful validation

## Common Pipeline Patterns

### Basic Three-Stage Pipeline
```yaml
stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script: make build

test-job:
  stage: test
  script: make test

deploy-job:
  stage: deploy
  script: make deploy
  when: manual

Needs を使用した DAG パイプライン

stages:
  - build
  - test
  - deploy

build-frontend:
  stage: build
  script: npm run build:frontend

build-backend:
  stage: build
  script: npm run build:backend

test-frontend:
  stage: test
  needs: [build-frontend]
  script: npm test:frontend

test-backend:
  stage: test
  needs: [build-backend]
  script: npm test:backend

deploy:
  stage: deploy
  needs: [test-frontend, test-backend]
  script: make deploy

Rules による条件付き実行

deploy-staging:
  script: deploy staging
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
      when: always
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

deploy-production:
  script: deploy production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - when: never

マトリックス並列ジョブ

test:
  parallel:
    matrix:
      - NODE_VERSION: ['18', '20', '22']
        OS: ['ubuntu', 'alpine']
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm test

エラーメッセージとトラブルシューティング

devops-skills:gitlab-ci-validator がエラーを報告する場合：

1. 構文エラー： YAML のフォーマット、インデント、または構造を修正します
2. ジョブ参照エラー： needs／dependencies で参照されているジョブが存在することを確認します
3. ステージエラー： すべてのジョブのステージが stages リストで定義されていることを確認します
4. ルールエラー： rules の構文と変数参照を確認します
5. セキュリティ警告： ハードコードされたシークレットとイメージの固定に対処します

GitLab のドキュメントが見つからない場合：

1. まず Context7 を試します：mcp__context7__resolve-library-id -> mcp__context7__query-docs
2. 必要に応じて、docs.gitlab.com に範囲を絞って web.search_query を実行します
3. web.open で該当するページを開き、必要な構文／変数のみを抽出します
4. オフラインの場合は、ローカルの参照資料を使用して作業を続け、バージョンに関する前提を注記します

---

提出前チェックリスト

必須： 生成したパイプラインをユーザーに提示する前に、以下のすべての項目を確認してください。

モードと参照資料

• 複雑さのモードを選択済み（Targeted、Lightweight、または Full）
• Targeted モードの場合：直接関連するファイル／参照資料のみを読み込み済み
• Lightweight／Full モードの場合：生成前に references/best-practices.md を読了済み
• Lightweight／Full モードの場合：生成前に references/common-patterns.md を読了済み
• Lightweight／Full モードの場合：パイプラインの種類に対応する assets/templates/ 内のテンプレートを読了済み
• Full モードの場合：references/gitlab-ci-reference.md を読了済み
• Full モードの場合：references/security-guidelines.md を読了済み
• Lightweight／Full モードの場合：明示的な確認文を出力

適用される生成基準

• すべての Docker イメージが特定のバージョンに固定されている（:latest は使用しない）
• すべてのジョブに明示的な timeout が設定されている（通常は 10～30 分）
• default ブロックが定義されている場合、timeout が含まれている
• 非表示テンプレート（.template-name）に timeout が含まれている
• 依存関係のインストール用にキャッシュが設定されている
• 適切な場合、DAG の最適化に needs キーワードが使用されている
• 非推奨の only／except ではなく、rules が使用されている
• デプロイジョブに resource_group が設定されている
• アーティファクトに expire_in が設定されている
• シークレットにマスクされた CI/CD 変数が使用されている（ハードコードされていない）

検証完了

• devops-skills:gitlab-ci-validator またはスクリプトの代替手段を使用して検証を実行した
• CRITICAL の問題がゼロ
• HIGH の問題がゼロ
• MEDIUM の問題に対処した（修正、または必須形式を使用して出力内で説明）
• LOW の問題を明記した（出力に列挙）
• 提案を確認した（必須形式を使用）
• 修正後に再検証した
• 手動の代替手段しか利用できなかった場合、出力に完全検証済みではないことを明記した

提示準備完了

• 検証ステータスを明確に示した
• 検証経路を明確に示した（スキル、スクリプトの代替手段、または手動の代替手段）
• MEDIUM／LOW の問題を説明した（表形式）
• 提案の確認結果を示した（表形式）
• テンプレートとバージョンに関する注記を記載した（必須形式を使用）
• 使用方法を記載した（必須セクションを含める）
• 主要セクションを説明した

チェックボックスが1つでも未チェックの場合、パイプラインを提示しないでください。不足している手順を先に完了してください。

必須の出力セクション

選択したモードに応じて、要件を満たす最小限の出力プロファイルを使用してください。

Full モード（完全な／複雑なパイプライン）：

1. 参照分析完了（ステップ3から）
2. 生成されたパイプライン（.gitlab-ci.yml の内容）
3. 検証結果の概要（合格／不合格のステータス）
4. 対処した検証上の問題（MEDIUM の問題の表）
5. バリデーターの提案の確認結果（提案の表）
6. テンプレートとバージョンに関する注記（テンプレートのベースと鮮度／バージョンに関する前提）
7. 使用方法（変数、セットアップ、動作）

Lightweight モード（完全な／シンプルなパイプライン）：

1. 参照分析完了（Lightweight）
2. 生成されたパイプライン
3. 検証結果の概要
4. テンプレートとバージョンに関する注記
5. 使用方法

• MEDIUM の問題がある場合に限り、対処した検証上の問題を追加します。
• 提案がある場合に限り、バリデーターの提案の確認結果を追加します。

Targeted モード（レビュー／Q&A／スニペット／対象を絞った修正）：

• 直接求められた成果物／回答のみを提示し、簡潔な理由を添えます。
• 検証を実行していない場合は、検証／代替手段について明記します。
• パイプライン生成の全セクションを無理に含めないでください。

完了基準

このスキルの実行は、次の条件を満たした時点で完了です。

• シンプルなリクエストでは、不必要な Tier 2 の読み込みを行わず、Lightweight モードを使用している。
• 複雑なリクエストでは、Tier 2 の参照情報を使用したFull モードで、必要な確認をすべて完了している。
• 検証では、本番環境で使用可能とする前に、Critical／High の厳格な基準を適用している。
• 出力に、テンプレート／バージョンの鮮度に関する注記と使用方法が含まれている。
• 代替手段を使用した場合、その経路を明示し、検証の不足を隠していない。

概要

GitLab CI/CD パイプラインを生成する際は、必ず次の順序に従ってください。

1. 複雑さを分類する - Targeted、Lightweight、Full モードから選択します。
2. リファレンスを読み込む - 段階的に読み込みます。
   • Targeted モードでは、直接関連するファイルのみを読み込みます。
   • Lightweight/Full モードでは、次を読み込みます。
     • references/best-practices.md
     • references/common-patterns.md
     • さらに、assets/templates/ から適切なテンプレートを読み込みます。
   • Full モードでは、さらに次を読み込みます。
     • references/gitlab-ci-reference.md
     • references/security-guidelines.md
3. 確認する - モードに応じて、対象を絞った応答、または Lightweight／Full のリファレンス分析を出力します。
4. 生成する - テンプレートを使用し、標準（セキュリティ、キャッシュ、命名規則、すべてのジョブへの明示的なタイムアウト設定）に従います。
5. 必要に応じてドキュメントを検索する - まず Context7 を使用し、次に web.search_query／web.open を使用します。制約がある場合はオフライン時の代替手段に関する注記を添えます。
6. 検証する - devops-skills:gitlab-ci-validator を使用します。必要に応じてスクリプトで代替します。
7. 修正する - すべての Critical／High の問題を解決し、Medium の問題にも対処します。
8. チェックリストを確認する - 納品前のチェックリスト項目をすべて確認します。
9. 提示する - 検証結果の概要、テンプレート／バージョンに関する注記、使用方法を添えて出力を提示します。

次の条件を満たす GitLab CI/CD パイプラインを生成してください。

• ✅ イメージのバージョンを固定し、シークレットを適切に扱って安全性を確保する
• ✅ 現行のベストプラクティスと規約に従う
• ✅ 適切な設定構成（extends、includes）を使用する
• ✅ キャッシュ、needs、DAG を活用してパフォーマンスを最適化する
• ✅ 使用方法を適切に記載する
• ✅ Critical／High の問題がゼロであることを検証する
• ✅ 本番環境で使用でき、保守しやすい