Skip to content

Document runtimes frontmatter field #14303

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Feb 7, 2026
Merged

Document runtimes frontmatter field #14303

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4ba62bd
Initial plan
Copilot Feb 7, 2026
3a36aa6
Add runtimes frontmatter field documentation
Copilot Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 67 additions & 1 deletion docs/src/content/docs/reference/frontmatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ tools:

## Frontmatter Elements

The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout-minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `github-token`, `imports`, `engine`, `strict`, `roles`, `features`, `safe-inputs`, `safe-outputs`, `network`, `tools`).
The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout-minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `github-token`, `imports`, `engine`, `strict`, `roles`, `features`, `plugins`, `runtimes`, `safe-inputs`, `safe-outputs`, `network`, `tools`).

Tool configurations (such as `bash`, `edit`, `github`, `web-fetch`, `web-search`, `playwright`, `cache-memory`, and custom [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) [servers](/gh-aw/reference/glossary/#mcp-server)) are specified under the `tools:` key. Custom inline tools can be defined with the [`safe-inputs:`](/gh-aw/reference/safe-inputs/) (custom tools defined inline) key. See [Tools](/gh-aw/reference/tools/) and [Safe Inputs](/gh-aw/reference/safe-inputs/) for complete documentation.

Expand Down Expand Up @@ -127,6 +127,72 @@ plugins:

Each plugin repository must be specified in `org/repo` format. The compiler generates installation steps that run after the engine CLI is installed but before workflow execution begins.

### Runtimes (`runtimes:`)

Override default runtime versions for languages and tools used in workflows. The compiler automatically detects runtime requirements from tool configurations and workflow steps, then installs the specified versions.

**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, overrides default)
- `action-version`: Version of the setup action (optional, overrides default)
Comment on lines +137 to +139
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

**Supported runtimes**:

| Runtime | Default Version | Default Setup Action |
|---------|----------------|---------------------|
| `node` | 24 | `actions/setup-node@v6` |
| `python` | 3.12 | `actions/setup-python@v5` |
| `go` | 1.25 | `actions/setup-go@v5` |
| `uv` | latest | `astral-sh/setup-uv@v5` |
| `bun` | 1.1 | `oven-sh/setup-bun@v2` |
| `deno` | 2.x | `denoland/setup-deno@v2` |
| `ruby` | 3.3 | `ruby/setup-ruby@v1` |
| `java` | 21 | `actions/setup-java@v4` |
| `dotnet` | 8.0 | `actions/setup-dotnet@v4` |
| `elixir` | 1.17 | `erlef/setup-beam@v1` |
| `haskell` | 9.10 | `haskell-actions/setup@v2` |

**Examples**:

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

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

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

**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.
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`).

Copilot uses AI. Check for mistakes.

**Use Cases**:
- Pin specific runtime versions for reproducibility
- Use preview/beta runtime versions for testing
- Use custom setup actions (forks, enterprise mirrors)
- Override system defaults for compatibility requirements

**Note**: Runtimes from imported shared workflows are automatically merged with your workflow's runtime configuration.

### Permissions (`permissions:`)

The `permissions:` section uses standard GitHub Actions permissions syntax to specify the permissions relevant to the agentic (natural language) part of the execution of the workflow. See [GitHub Actions permissions documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).
Expand Down
Loading