Generate YAML Schema for GitHub Actions Workflows

Q: Generate YAML Schema for GitHub Actions Workflows

## GitHub Actions Workflow to YAML Schema GitHub Actions workflows are YAML files with specific structural requirements. Converting a sample workflow JSON to YAML Schema creates a validation layer that catches workflow errors locally. ### Example Workflow JSON json { "name": "CI Pipeline", "on": { "push": { "branches": ["main"], "paths": ["src/", "package.json"] }, "pull_request": { "branches": ["main"] }, "schedule": [ { "cron": "0 6 * * 1" }

Learn how to convert GitHub Actions workflow JSON into YAML Schema definitions. Covers trigger events, job definitions, step validation, action inputs, secrets references, and reusable workflows.

Real-World Configs

Detailed Explanation

GitHub Actions Workflow to YAML Schema

GitHub Actions workflows are YAML files with specific structural requirements. Converting a sample workflow JSON to YAML Schema creates a validation layer that catches workflow errors locally.

Example Workflow 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" }
      ]
    }
  }
}

Generated 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

Trigger Event Validation

The on field supports many event types. The schema ensures only valid event names are used and that event-specific properties (like branches for push) are correctly structured.

Action Reference Format

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

This validates the owner/repo@ref format for action references.

Matrix Strategy Validation

The matrix strategy creates multiple job runs with different parameter combinations. The schema validates the matrix structure while allowing any parameter names.

Secrets and Expression Validation

While the schema cannot validate GitHub Actions expressions (${{ ... }}) at the structural level, it ensures that the fields where expressions are used have the correct type (string for most expression contexts).

Use Case

Organizations with hundreds of repositories need consistent GitHub Actions workflows. A YAML schema for workflows enables IDE-powered autocompletion, validates trigger configurations, ensures job dependencies are correctly defined, and catches syntax errors that would otherwise only surface after pushing to GitHub.

Try It — JSON to YAML Schema

Open full tool →