Document runtimes frontmatter field

[Copilot]

The runtimes: frontmatter field exists in schema and implementation but was undocumented, forcing users to read JSON schemas to discover runtime version overrides.

Changes

• Added runtimes documentation section to docs/src/content/docs/reference/frontmatter.md

  • Table of 11 supported runtimes with default versions (node 24, python 3.12, go 1.25, etc.)
  • Configuration fields: version, action-repo, action-version
  • Usage examples for single and multi-runtime overrides
  • Default behavior and runtime merging from imports

• Updated frontmatter elements list to include runtimes field

Example

---
runtimes:
  node:
    version: "22"
  python:
    version: "3.11"
  go:
    version: "1.22"
    action-repo: "actions/setup-go"
    action-version: "v5"
---

Users can now discover and configure runtime versions without consulting schemas or implementation code.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Document runtimes frontmatter configuration field</issue_title>
<issue_description>### 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 github/gh-aw#14066

AI generated by Discussion Task Miner - Code Quality Improvement Agent

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

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Document runtimes frontmatter configuration field #14135

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

Documents the previously-undocumented runtimes: frontmatter field so users can discover and configure runtime version/setup-action overrides without reading schemas/implementation.

Changes:

• Adds a new runtimes: reference section with supported runtimes, defaults, fields, and examples.
• Updates the “Frontmatter Elements” list to include plugins and runtimes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

version is documented as required, but the schema and implementation treat it as optional (omitting it uses the runtime’s default version). This also allows specifying only action-repo/action-version without a version override. Please update the field description to reflect that version is optional and defaults apply when omitted.

Suggested change

	- `version`: Runtime version string (required)
	- `action-repo`: Custom GitHub Actions setup action (optional, overrides default)
	- `action-version`: Version of the setup action (optional, overrides default)
	- `version`: Runtime version string (optional; if omitted, the runtime's default version is used)
	- `action-repo`: Custom GitHub Actions setup action (optional, overrides default even without a `version` override)
	- `action-version`: Version of the setup action (optional, overrides default even without a `version` override)

[Copilot]

The runtime auto-detection example here references bash: ["node"] / bash: ["python"], but runtime detection doesn’t inspect tools.bash allowlists; it detects runtimes from run: commands (custom steps / engine steps) and from certain MCP tool configs (e.g., a non-containerized MCP server command) and Serena local mode. Please replace the example with something that matches the actual detection behavior (e.g., run: npm install / run: python script.py, or a custom MCP tool command: node).

Suggested change

	**Default Behavior**: If not specified, workflows use default runtime versions as defined in the system. The compiler automatically detects which runtimes are needed based on tool configurations (e.g., `bash: ["node"]`, `bash: ["python"]`) and workflow steps.
	**Default Behavior**: If not specified, workflows use default runtime versions as defined in the system. The compiler automatically detects which runtimes are needed based on tool configurations and workflow steps (e.g., `run: npm install`, `run: python script.py`, or an MCP tool `command: node`).