CI/CDパイプライン設定用のYAML Schemaを生成する

CI/CDパイプライン設定スキーマ

CI/CDパイプラインファイル（GitHub Actions、GitLab CI、Azure Pipelines）は予測可能なパターンに従います。サンプルパイプラインJSONをYAML Schemaに変換することで、コミット前に設定エラーを検出する検証レイヤーを作成します。

パイプラインJSONの例

{
  "name": "Build and Deploy",
  "on": {
    "push": {
      "branches": ["main", "develop"]
    },
    "pull_request": {
      "branches": ["main"]
    }
  },
  "jobs": {
    "build": {
      "runsOn": "ubuntu-latest",
      "steps": [
        {
          "name": "Checkout",
          "uses": "actions/checkout@v4"
        },
        {
          "name": "Setup Node",
          "uses": "actions/setup-node@v4",
          "with": {
            "nodeVersion": "20"
          }
        },
        {
          "name": "Install",
          "run": "npm ci"
        },
        {
          "name": "Test",
          "run": "npm test"
        }
      ]
    }
  }
}

生成されるYAML Schema

type: object
properties:
  name:
    type: string
    description: Actionsタブに表示されるワークフロー名
  on:
    type: object
    properties:
      push:
        type: object
        properties:
          branches:
            type: array
            items:
              type: string
      pull_request:
        type: object
        properties:
          branches:
            type: array
            items:
              type: string
  jobs:
    type: object
    patternProperties:
      "^[a-z][a-z0-9_-]*$":
        type: object
        properties:
          runsOn:
            type: string
            enum:
              - ubuntu-latest
              - ubuntu-22.04
              - macos-latest
              - windows-latest
          steps:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                uses:
                  type: string
                  pattern: "^[a-zA-Z0-9-]+/[a-zA-Z0-9-]+@.+$"
                run:
                  type: string
                with:
                  type: object
              oneOf:
                - required: [uses]
                - required: [run]
            minItems: 1
        required:
          - runsOn
          - steps
required:
  - name
  - on
  - jobs

CI/CDの主要スキーマパターン

ステップ型の検証 -- 各ステップはuses（アクション）またはrun（スクリプト）のいずれかを持たなければならず、両方は不可：

oneOf:
  - required: [uses]
    properties:
      run: false
  - required: [run]
    properties:
      uses: false

マトリックス戦略：

strategy:
  type: object
  properties:
    matrix:
      type: object
      patternProperties:
        ".*":
          type: array
          items:
            type: [string, integer]

環境変数：

env:
  type: object
  patternProperties:
    "^[A-Z][A-Z0-9_]*$":
      type: string

条件実行

if:
  type: string
  description: >
    ステップが実行されるかどうかを決定する
    GitHub Actions式。
  examples:
    - "github.ref == 'refs/heads/main'"
    - "always()"
    - "success()"

CI/CDスキーマ検証のメリット

1. 構文エラーをローカルで検出 プッシュ前に
2. IDE自動補完 スキーマ対応エディターで
3. タイプミスを防止 ランナー名、アクション参照で
4. 標準を強制 チームリポジトリ全体で