[Code Quality] Document runtimes frontmatter configuration field

[github-actions]

Description

The runtimes: frontmatter field is fully defined in the schema but is missing from main frontmatter documentation. Users cannot discover how to override runtime versions (Node.js, Python, etc.) without reading the schema.

Current State

Schema: Fully defined with version, action-repo, and action-version ✅
Implementation: Handled in runtime setup code ✅
Documentation: Missing from main frontmatter documentation ❌

Schema Definition

runtimes:
  node:
    version: "22"
  python:
    version: "3.12"
    action-repo: "actions/setup-python"
    action-version: "v5"
  go:
    version: "1.23"
  uv:
    version: "0.5.16"

Suggested Documentation Section

Add to docs/src/content/docs/reference/frontmatter.md:

### `runtimes`

Override default runtime versions for languages and tools used in workflows.

**Format**: Object with runtime name as key and configuration as value

**Fields per runtime**:
- `version`: Runtime version string (required)
- `action-repo`: Custom GitHub Actions setup action (optional)
- `action-version`: Version of the setup action (optional)

**Supported runtimes**:
- `node`: Node.js runtime
- `python`: Python runtime
- `go`: Go runtime
- `uv`: uv package installer
- `bun`: Bun runtime
- `deno`: Deno runtime

**Examples**:

Override Node.js version:
```yaml
runtimes:
  node:
    version: "22"
```

Use specific Python version with custom setup action:
```yaml
runtimes:
  python:
    version: "3.12"
    action-repo: "actions/setup-python"
    action-version: "v5"
```

Multiple runtime overrides:
```yaml
runtimes:
  node:
    version: "20"
  python:
    version: "3.11"
  go:
    version: "1.22"
```

**Default Behavior**: If not specified, workflows use default runtime versions defined in the system.

Use Cases

• Pin specific runtime versions for reproducibility
• Use preview/beta runtime versions
• Use custom setup actions (forks, enterprise mirrors)
• Override system defaults for compatibility

Files Affected

• docs/src/content/docs/reference/frontmatter.md (add new section)
• pkg/parser/schemas/main_workflow_schema.json (already has definition)
• Runtime setup code in pkg/workflow/ (implementation exists)

Success Criteria

• Documentation section added to frontmatter reference
• All supported runtimes listed
• Configuration fields explained
• Examples for common use cases
• Cross-reference to GitHub Actions setup actions

Priority

Medium - Advanced users need this for custom runtime environments

Estimated Effort

2-3 hours (documentation writing + testing examples)

Source

Extracted from Schema Consistency Audit - February 2026 #14066

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 7, 2026, 1:24 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster