GitHub Actionsワークフロー用のYAML Schemaを生成する

GitHub ActionsワークフローからYAML Schemaへ

GitHub Actionsワークフローは特定の構造要件を持つYAMLファイルです。サンプルワークフローJSONをYAML Schemaに変換することで、ワークフローエラーをローカルで検出する検証レイヤーを作成します。

ワークフローJSONの例

{
  "name": "CI Pipeline",
  "on": {
    "push": {
      "branches": ["main"],
      "paths": ["src/**", "package.json"]
    },
    "pull_request": {
      "branches": ["main"]
    },
    "schedule": [
      { "cron": "0 6 * * 1" }
    ]
  },
  "permissions": {
    "contents": "read",
    "packages": "write"
  },
  "jobs": {
    "lint": {
      "runsOn": "ubuntu-latest",
      "steps": [
        { "uses": "actions/checkout@v4" },
        { "uses": "actions/setup-node@v4", "with": { "nodeVersion": "20" } },
        { "run": "npm ci" },
        { "run": "npm run lint" }
      ]
    },
    "test": {
      "runsOn": "ubuntu-latest",
      "needs": ["lint"],
      "strategy": {
        "matrix": {
          "nodeVersion": ["18", "20", "22"]
        }
      },
      "steps": [
        { "uses": "actions/checkout@v4" },
        {
          "uses": "actions/setup-node@v4",
          "with": { "nodeVersion": "${{ matrix.nodeVersion }}" }
        },
        { "run": "npm ci" },
        { "run": "npm test" }
      ]
    }
  }
}

生成されるYAML Schema

type: object
properties:
  name:
    type: string
    maxLength: 100
  on:
    type: object
    properties:
      push:
        type: object
        properties:
          branches:
            type: array
            items:
              type: string
          paths:
            type: array
            items:
              type: string
          tags:
            type: array
            items:
              type: string
      pull_request:
        type: object
        properties:
          branches:
            type: array
            items:
              type: string
      schedule:
        type: array
        items:
          type: object
          properties:
            cron:
              type: string
              pattern: "^[\\d*,/-]+ [\\d*,/-]+ [\\d*,/-]+ [\\d*,/-]+ [\\d*,/-]+$"
          required:
            - cron
      workflow_dispatch:
        type: object
  permissions:
    type: object
    patternProperties:
      "^[a-z-]+$":
        type: string
        enum: [read, write, none]
  env:
    type: object
    patternProperties:
      "^[A-Z][A-Z0-9_]*$":
        type: string
  jobs:
    type: object
    patternProperties:
      "^[a-z][a-z0-9_-]*$":
        type: object
        properties:
          runsOn:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          needs:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          strategy:
            type: object
            properties:
              matrix:
                type: object
              failFast:
                type: boolean
                default: true
          steps:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                uses:
                  type: string
                run:
                  type: string
                with:
                  type: object
                env:
                  type: object
                if:
                  type: string
            minItems: 1
          if:
            type: string
          environment:
            type: string
          concurrency:
            type: [string, object]
        required:
          - runsOn
          - steps
    minProperties: 1
required:
  - name
  - on
  - jobs

トリガーイベントの検証

onフィールドは多くのイベントタイプをサポートしています。スキーマは有効なイベント名のみが使用され、イベント固有のプロパティ（pushのbranchesなど）が正しく構造化されていることを保証します。

アクション参照のフォーマット

uses:
  type: string
  pattern: "^[a-zA-Z0-9-]+/[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$"

これはアクション参照のowner/repo@refフォーマットを検証します。

マトリックス戦略の検証

マトリックス戦略は異なるパラメータの組み合わせで複数のジョブ実行を作成します。スキーマはマトリックス構造を検証しながら、任意のパラメータ名を許可します。

secretsと式の検証

スキーマはGitHub Actions式（${{ ... }}）を構造レベルでは検証できませんが、式が使用されるフィールドが正しい型（ほとんどの式コンテキストでstring）を持つことを保証します。