Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
75 changes: 75 additions & 0 deletions docs/adr/29094-lenient-string-coercion-for-toolsets-field.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# ADR-29094: Lenient String Coercion for `tools.github.toolsets` Field

**Date**: 2026-04-29
**Status**: Draft
**Deciders**: pelikhan, Copilot

---

## Part 1 — Narrative (Human-Friendly)

### Context

The `tools.github.toolsets` field in workflow frontmatter configures which GitHub toolsets are available to the agent. The field is semantically a list, so the schema declared it as `type: array`. Users writing the natural YAML scalar shorthand `toolsets: "default"` received a terse "got string, want array" validation error with no example and no list of valid values. This was a frequent friction point for single-toolset configurations, where wrapping a single name in brackets feels redundant. The error gave no guidance on what values were valid or that `[default]` was the required spelling.

### Decision

We will accept a bare string for `tools.github.toolsets` (and its alias `tools.github.toolset`) and coerce it to a one-element slice at parse time. The raw config map is immediately normalized from `string` → `[]any` so that compiled GitHub Actions YAML always emits an array, regardless of what the user wrote. The JSON schema is updated to allow both forms via `oneOf` (string | array). A field-specific hint is added to `knownOneOfFieldHints` in the error-formatting layer, so that any remaining type error (e.g., the user passes an integer) surfaces valid toolset names and both accepted syntax forms.

### Alternatives Considered

#### Alternative 1: Improve the error message only — keep strict `type: array`

Keep the schema requiring an array but rewrite the validation error to list valid toolset names and suggest the `[default]` bracket syntax. This eliminates the unhelpful error without changing the schema or parser. It was not chosen because it still forces users to change their YAML even when their intent is clear: a single string unambiguously means a one-element list. The UX improvement is incomplete if the user's YAML still fails.

#### Alternative 2: Accept string only — deprecate the array form

Simplify to a single `type: string` that names one toolset per workflow. This is the most restrictive approach and breaks all existing configs that use multiple toolsets (`toolsets: [default, repos]`). It was not chosen because multiple-toolset configurations are a documented and used feature.

### Consequences

#### Positive
- Single-toolset configurations can use natural YAML scalar syntax (`toolsets: default`) without brackets.
- Error messages for invalid types now include valid toolset names and both accepted syntax forms, reducing trial-and-error debugging.
- The same `oneOf` pattern already used for `/engine` is now applied consistently to `/tools/github/toolsets`.

#### Negative
- The parser has two code paths for the same field (`[]any` branch and `string` branch), increasing maintenance surface.
- The parser mutates the raw config map (normalizing `string` → `[]any`) as a side effect of parsing, coupling the parsing step to downstream serialization concerns.
- `oneOf` schemas can produce multi-branch validation noise for unrelated errors; the existing `cleanOneOfMessage` cleanup function mitigates this but adds indirection.

#### Neutral
- The singular `toolset` field receives identical treatment for consistency.
- The `github_toolset_name` definition is shared in the schema `$defs` section to avoid duplication between the string and array branches.
- No migration is required: existing array-form configurations continue to work unchanged.

---

## Part 2 — Normative Specification (RFC 2119)

> The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this section are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

### Toolset Field Parsing

1. Implementations **MUST** accept a bare YAML string for `tools.github.toolsets` and `tools.github.toolset` and treat it as equivalent to a one-element array containing that string.
2. Implementations **MUST** accept a YAML array of strings for `tools.github.toolsets` and `tools.github.toolset`.
3. Implementations **MUST NOT** accept any other type (integer, boolean, object, etc.) for these fields; such values **MUST** produce a validation error.
4. Implementations **MUST** normalize the raw config map entry for `toolsets` or `toolset` from a bare string to a `[]any` slice before serialization so that compiled output always emits an array.

### Schema Definition

1. The JSON schema for `tools.github.toolsets` **MUST** declare the field using `oneOf` with exactly two branches: one `type: string` branch and one `type: array` branch whose items reference a shared `github_toolset_name` definition.
2. The `github_toolset_name` definition **MUST** be placed in the top-level `$defs` section of the schema and **MUST** be referenced (not inlined) from both branches to avoid duplication.

### Error Hints

1. When schema validation produces an `oneOf` type-conflict error for the path `/tools/github/toolsets`, the error formatter **MUST** append a hint listing valid toolset names and both accepted syntax forms (string and array).
2. Error hints **SHOULD** include a concrete YAML example demonstrating each accepted form.

### Conformance

An implementation is considered conformant with this ADR if it satisfies all **MUST** and **MUST NOT** requirements above. Failure to meet any **MUST** or **MUST NOT** requirement constitutes non-conformance.

---

*This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/25109741675) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*
16 changes: 12 additions & 4 deletions docs/src/content/docs/reference/frontmatter-full.md
Original file line number Diff line number Diff line change
Expand Up @@ -1947,11 +1947,19 @@ tools:
# (optional)
github-token: "${{ secrets.GITHUB_TOKEN }}"

# Array of GitHub MCP server toolset names to enable specific groups of GitHub API
# functionalities
# GitHub MCP server toolset name(s) to enable. Accepts a single toolset name
# (string) or an array of toolset names.
# (optional)
toolsets: []
# Array of Toolset name
# This field supports multiple formats (oneOf):

# Option 1: A single GitHub MCP server toolset name (shorthand for a one-element
# array)
toolsets: "all"

# Option 2: Array of GitHub MCP server toolset names to enable specific groups of
# GitHub API functionalities
toolsets: [default]
# Array items: Toolset name

# Volume mounts for the containerized GitHub MCP server (format:
# 'host:container:mode' where mode is 'ro' for read-only or 'rw' for read-write).
Expand Down
3 changes: 2 additions & 1 deletion pkg/parser/schema_errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,8 @@ var typeConflictGotWantPattern = regexp.MustCompile(`(?:^|: )got (\w+), want (\w
// The engine list mirrors the built-in engines in NewEngineCatalog.
// Update this list when built-in engines change.
var knownOneOfFieldHints = map[string]string{
"/engine": "Valid engine names: claude, codex, copilot, gemini.\n\nExample:\nengine: copilot",
"/engine": "Valid engine names: claude, codex, copilot, gemini.\n\nExample:\nengine: copilot\n# or with options:\nengine:\n id: copilot\n max-turns: 15",
"/tools/github/toolsets": "Valid toolsets: all, default, action-friendly, context, repos, issues, pull_requests, actions, code_security, dependabot, discussions, experiments, gists, labels, notifications, orgs, projects, search, secret_protection, security_advisories, stargazers, users.\n\nExample:\ntools:\n github:\n toolsets: default\n # or as an array:\n toolsets: [default, repos]",
}

// synthesizeOneOfTypeConflictMessage produces a plain-English error message when every
Expand Down
18 changes: 18 additions & 0 deletions pkg/parser/schema_errors_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,24 @@ func TestSynthesizeOneOfTypeConflictMessage(t *testing.T) {
},
wantAny: []string{"expected string or object, got number", "Valid engine names", "copilot"},
},
{
name: "engine hint includes object form example",
lines: []string{
"at '/engine': 'oneOf' failed, none matched",
"- at '/engine': got number, want string",
"- at '/engine': got number, want object",
},
wantAny: []string{"id: copilot", "max-turns"},
},
{
name: "toolsets field with number type produces actionable message",
lines: []string{
"at '/tools/github/toolsets': 'oneOf' failed, none matched",
"- at '/tools/github/toolsets': got number, want string",
"- at '/tools/github/toolsets': got number, want array",
},
wantAny: []string{"expected string or array, got number", "Valid toolsets", "default", "toolsets: default"},
},
{
name: "unknown field produces generic message without hints",
lines: []string{
Expand Down
97 changes: 64 additions & 33 deletions pkg/parser/schemas/main_workflow_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -3561,39 +3561,42 @@
"description": "Optional custom GitHub token (e.g., '${{ secrets.CUSTOM_PAT }}'). For 'remote' type, defaults to GH_AW_GITHUB_TOKEN if not specified."
},
"toolsets": {
"type": "array",
"description": "Array of GitHub MCP server toolset names to enable specific groups of GitHub API functionalities",
"items": {
"type": "string",
"description": "Toolset name",
"enum": [
"all",
"default",
"action-friendly",
"context",
"repos",
"issues",
"pull_requests",
"actions",
"code_security",
"dependabot",
"discussions",
"experiments",
"gists",
"labels",
"notifications",
"orgs",
"projects",
"search",
"secret_protection",
"security_advisories",
"stargazers",
"users"
]
},
"minItems": 1,
"$comment": "At least one toolset is required when toolsets array is specified. Use null or omit the field to use all toolsets.",
"maxItems": 20
"description": "GitHub MCP server toolset name(s) to enable. Accepts a single toolset name (string) or an array of toolset names.",
"oneOf": [
{

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

@copilot refactor into shared type

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in 0232f2e. The toolset enum is now defined once as $defs/github_toolset_name and both the string and array-items branches use $ref: "#/$defs/github_toolset_name".

"$ref": "#/$defs/github_toolset_name",
"description": "A single GitHub MCP server toolset name (shorthand for a one-element array)"
},
{
"type": "array",
"description": "Array of GitHub MCP server toolset names to enable specific groups of GitHub API functionalities",
"items": {
"$ref": "#/$defs/github_toolset_name"
Comment on lines 3563 to +3574
},
"minItems": 1,
"$comment": "At least one toolset is required when toolsets array is specified. Omit the field to use all toolsets.",
"maxItems": 20
}
]
},
"toolset": {
"description": "Deprecated. Use 'toolsets' instead.",
"deprecated": true,
"oneOf": [
{
"$ref": "#/$defs/github_toolset_name",
"description": "A single GitHub MCP server toolset name (shorthand for a one-element array)"
},
{
"type": "array",
"description": "Array of GitHub MCP server toolset names",
"items": {
"$ref": "#/$defs/github_toolset_name"
},
"minItems": 1,
"maxItems": 20
}
]
},
"mounts": {
"type": "array",
Expand Down Expand Up @@ -9353,6 +9356,34 @@
}
],
"$defs": {
"github_toolset_name": {
"type": "string",
"description": "A GitHub MCP server toolset name that enables a specific group of GitHub API functionalities.",
"enum": [
"all",
"default",
"action-friendly",
"context",
"repos",
"issues",
"pull_requests",
"actions",
"code_security",
"dependabot",
"discussions",
"experiments",
"gists",
"labels",
"notifications",
"orgs",
"projects",
"search",
"secret_protection",
"security_advisories",
"stargazers",
"users"
]
},
"non_empty_string": {
"type": "string",
"minLength": 1,
Expand Down
15 changes: 14 additions & 1 deletion pkg/workflow/tools_parser.go
Original file line number Diff line number Diff line change
Expand Up @@ -247,21 +247,34 @@ func parseGitHubTool(val any) *GitHubToolConfig {
config.GitHubToken = token
}

// Check for both "toolset" and "toolsets" (plural is more common in user configs)
// Check for both "toolset" and "toolsets" (plural is more common in user configs).
// Both fields accept either a single string (coerced to a one-element slice) or an
// array of strings, so that users can write either `toolsets: "default"` or
// `toolsets: [default]`.
if toolset, ok := configMap["toolsets"].([]any); ok {
config.Toolset = make(GitHubToolsets, 0, len(toolset))
for _, item := range toolset {
if str, ok := item.(string); ok {
config.Toolset = append(config.Toolset, GitHubToolset(str))
}
}
} else if toolsetStr, ok := configMap["toolsets"].(string); ok {
config.Toolset = GitHubToolsets{GitHubToolset(toolsetStr)}
// Normalize the raw map to an array so the compiled GitHub Actions YAML
// always emits an array, maintaining consistent output regardless of input form.
configMap["toolsets"] = []any{toolsetStr}
} else if toolset, ok := configMap["toolset"].([]any); ok {
config.Toolset = make(GitHubToolsets, 0, len(toolset))
for _, item := range toolset {
if str, ok := item.(string); ok {
config.Toolset = append(config.Toolset, GitHubToolset(str))
}
}
} else if toolsetStr, ok := configMap["toolset"].(string); ok {
config.Toolset = GitHubToolsets{GitHubToolset(toolsetStr)}
// Normalize the raw map to an array so the compiled GitHub Actions YAML
// always emits an array, maintaining consistent output regardless of input form.
configMap["toolset"] = []any{toolsetStr}
}

if lockdown, ok := configMap["lockdown"].(bool); ok {
Expand Down
70 changes: 70 additions & 0 deletions pkg/workflow/tools_types_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,76 @@ func TestGitHubConfigParsing(t *testing.T) {
t.Errorf("expected 2 toolsets, got %d", len(config.Toolset))
}
})

t.Run("coerces single string toolsets to slice", func(t *testing.T) {
toolsMap := map[string]any{
"github": map[string]any{
"toolsets": "default",
},
}

tools := NewTools(toolsMap)
config := tools.GitHub

if config == nil {
t.Fatal("expected non-nil config")
}

if len(config.Toolset) != 1 {
t.Fatalf("expected 1 toolset, got %d", len(config.Toolset))
}
if config.Toolset[0] != "default" {
t.Errorf("expected toolset 'default', got %q", config.Toolset[0])
}

// Verify ToMap() emits an array so compiled YAML always renders an array
resultMap := tools.ToMap()
githubMap, ok := resultMap["github"].(map[string]any)
if !ok {
t.Fatalf("expected ToMap()[github] to be map[string]any, got %T", resultMap["github"])
}
normalized, ok := githubMap["toolsets"].([]any)
if !ok {
t.Errorf("expected ToMap()[github][toolsets] to be []any after coercion, got %T", githubMap["toolsets"])
} else if len(normalized) != 1 || normalized[0] != "default" {
t.Errorf("expected normalized toolsets to be [default], got %v", normalized)
}
})

t.Run("coerces single string toolset (singular) to slice", func(t *testing.T) {
toolsMap := map[string]any{
"github": map[string]any{
"toolset": "repos",
},
}

tools := NewTools(toolsMap)
config := tools.GitHub

if config == nil {
t.Fatal("expected non-nil config")
}

if len(config.Toolset) != 1 {
t.Fatalf("expected 1 toolset, got %d", len(config.Toolset))
}
if config.Toolset[0] != "repos" {
t.Errorf("expected toolset 'repos', got %q", config.Toolset[0])
}

// Verify ToMap() emits an array so compiled YAML always renders an array
resultMap := tools.ToMap()
githubMap, ok := resultMap["github"].(map[string]any)
if !ok {
t.Fatalf("expected ToMap()[github] to be map[string]any, got %T", resultMap["github"])
}
normalized, ok := githubMap["toolset"].([]any)
if !ok {
t.Errorf("expected ToMap()[github][toolset] to be []any after coercion, got %T", githubMap["toolset"])
} else if len(normalized) != 1 || normalized[0] != "repos" {
t.Errorf("expected normalized toolset to be [repos], got %v", normalized)
}
})
}

func TestPlaywrightConfigParsing(t *testing.T) {
Expand Down