pelikhan · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026
diff --git a/docs/adr/70865-compile-reference-doc-examples-as-regression-tests.md b/docs/adr/70865-compile-reference-doc-examples-as-regression-tests.md
@@ -0,0 +1,59 @@
+# ADR-70865: Expose sandbox.mcp.trusted-bots in the Schema and Compile Reference Doc Examples as Regression Tests
+
+**Date**: 2026-10-21
+**Status**: Draft
+**Deciders**: Not recorded; acceptance remains pending maintainer review.
+
+---
+
+### Context
+
+The [MCP gateway reference](../src/content/docs/reference/mcp-gateway.md) and the workflow validation contract had diverged. The compiler already extracts `sandbox.mcp.trusted-bots` and emits `trustedBots` into the gateway configuration, but the closed `sandbox.mcp` object in the [canonical workflow schema](../../pkg/parser/schemas/main_workflow_schema.json) did not expose that property. The OIDC example also needed root-level `mcp-servers`, `id-token: write`, and an explicit network allowlist. These examples need to exercise the same validation and compilation path as workflow files, rather than remain unchecked YAML fragments.
+
+Exposing the trusted-bot field also requires a bounded input contract. The generated configuration passes through a shell heredoc; JSON string encoding alone does not prevent shell expansion. Accepting arbitrary nonempty strings would therefore be insufficient. This ADR records the proposed contract and test strategy for [PR #70865](https://github.com/github/gh-aw/pull/70865), not maintainer approval or evidence of successful execution.
+
+### Decision
+
+Expose `sandbox.mcp.trusted-bots` as an optional, nonempty array of validated literal GitHub-style identities, such as `github-actions[bot]`. Require ASCII letters, digits, hyphens, or underscores, optionally followed by `[bot]`, in both schema validation and the renderer. Reject malformed identities, whitespace-only entries, shell substitutions, and template expressions rather than trimming or evaluating them. Remove the unreachable camelCase extraction alias: frontmatter accepts only `trusted-bots`, while generated gateway JSON uses `trustedBots`. These additional identities are merged by the gateway with its built-in list; they neither remove nor override built-in identities.
+
+Keep the two frontmatter examples as complete, titled `aw` blocks in the reference page. The [reference regression test](../../pkg/workflow/mcp_gateway_reference_test.go) extracts those exact blocks, compiles them with the real compiler, and checks generated lock-file substrings for trusted-bot configuration and OIDC configuration, permission, and environment forwarding. [Schema regression tests](../../pkg/parser/schema_trusted_bots_test.go) cover the input contract separately. This keeps published examples, schema validation, and compiler output connected without introducing a general documentation-test framework.
+
+### Alternatives Considered
+
+#### Alternative 1: Fix only the documentation text and schema, without tests
+
+This has the lowest immediate maintenance cost, but leaves no direct regression guard connecting the published examples to compiler behavior.
+
+#### Alternative 2: Keep duplicate copies of the examples as fixture files under `pkg/`
+
+Separate fixtures avoid parsing Markdown, but duplicate the examples and can pass while the published version breaks. Extracting the published blocks avoids that duplication.
+
+#### Alternative 3: Remove `trusted-bots` from the docs instead of allowing it in the schema
+
+Removal avoids expanding the schema but hides an existing compiler capability. A constrained schema entry makes the supported input explicit instead.
+
+#### Alternative 4: Accept arbitrary nonempty identity strings
+
+This matches the initial draft's broad string contract but permits values unsafe for the generated shell context. Strict literal identity validation is preferable to exposing arbitrary strings or treating JSON escaping as shell protection.
+
+### Consequences
+
+#### Positive
+- Valid literal bot identities have an explicit schema contract; invalid shapes and unsafe identity values are intended to fail before configuration generation.
+- Compiling the published blocks provides a focused regression signal for schema or compiler changes affecting these examples.
+- Complete workflow structure makes the examples less ambiguous. The OIDC server URL and audience remain placeholders requiring a real server and its trust configuration.
+
+#### Negative
+- The test depends on the exact fence string (`` ```aw wrap title=".github/workflows/<name>.md" ``) and the docs file path. Editing the docs layout or fence attributes can break the test even when behavior is unchanged.
+- Unit tests now read docs content, which mixes documentation and Go test concerns. Other contributors may not expect this coupling.
+- Strict validation intentionally rejects arbitrary strings previously accepted by extraction code, including values that are not literal bot identities.
+
+#### Neutral
+- The test asserts on substrings of the generated lock file, so changes to lock file formatting may require updating the expected strings.
+- Coverage is limited to these two examples. Compilation does not verify live OIDC authentication, remote-server authorization, gateway identity merging at runtime, or other snippets.
+- Test definitions and automated completion notices are not evidence that checks passed or changes were published. Validation results must be reported separately for the final revision.
+- This decision does not add `tools.github.refusal-labels` or change concurrency behavior.
+
+---
+
+*Draft retained pending maintainer acceptance; no decider or approval is inferred from automation.*
diff --git a/docs/src/content/docs/reference/mcp-gateway.md b/docs/src/content/docs/reference/mcp-gateway.md
@@ -387,6 +387,8 @@ payload_size_threshold = 262144   # 256KB - more aggressive disk storage
 
 The optional `trustedBots` field in the gateway configuration passes an additional list of GitHub bot identity strings to the gateway. The gateway merges this list with its own built-in trusted identity list to form the effective set of identities it recognizes.
 
+Workflow frontmatter accepts only the kebab-case `sandbox.mcp.trusted-bots` key. The compiler translates it into camelCase `gateway.trustedBots` in the generated gateway JSON; `trustedBots` is not a frontmatter alias.
+
 > **Important**: `trustedBots` is **additive**. The gateway maintains its own internal list of trusted bot identities. The `trustedBots` field extends that internal list with additional identities; it cannot remove or override the gateway's built-in trusted identities.
 
 **Configuration Example**:
@@ -407,17 +409,30 @@ The optional `trustedBots` field in the gateway configuration passes an addition
 
 **Frontmatter Example** (workflow author):
 
-```yaml
+```aw wrap title=".github/workflows/trusted-bots.md"
+---
+on: workflow_dispatch
+permissions:
+  contents: read
+  issues: read
+engine: copilot
+tools:
+  github:
+    toolsets: [issues]
 sandbox:
   mcp:
     trusted-bots:
       - github-actions[bot]
       - copilot-swe-agent[bot]
+---
+
+Summarize the open issues in this repository.
 ```
 
 **Requirements**:
 - `trustedBots` MUST be a non-empty array of strings when present
 - Each entry MUST be a non-empty string (typically a GitHub username such as `github-actions[bot]`)
+- When configured through workflow frontmatter, entries MUST contain only ASCII letters, digits, hyphens, or underscores, optionally followed by `[bot]`. The compiler also validates these characters before rendering the gateway configuration to prevent shell expansion.
 - `trustedBots` entries are **merged** with the gateway's internal built-in trusted identities to form the effective list passed to the gateway
 - `trustedBots` MUST NOT be used to remove or override entries in the gateway's internal built-in trusted identity list
 
@@ -1309,15 +1324,27 @@ In this case, the audience defaults to `"https://my-server.example.com/mcp"`.
 
 **Frontmatter Example** (workflow author):
 
-```yaml
-tools:
-  mcp-servers:
-    my-mcp-server:
-      type: http
-      url: "https://my-server.example.com/mcp"
-      auth:
-        type: github-oidc
-        audience: "https://my-server.example.com"
+```aw wrap title=".github/workflows/oidc-mcp.md"
+---
+on: workflow_dispatch
+permissions:
+  contents: read
+  id-token: write
+engine: copilot
+network:
+  allowed:
+    - defaults
+    - my-server.example.com
+mcp-servers:
+  my-mcp-server:
+    type: http
+    url: "https://my-server.example.com/mcp"
+    auth:
+      type: github-oidc
+      audience: "https://my-server.example.com"
+---
+
+Use my-mcp-server to summarize the available project information.
 ```
 
 #### 7.6.2 Interaction with Static Headers

diff --git a/pkg/parser/schema_trusted_bots_test.go b/pkg/parser/schema_trusted_bots_test.go
@@ -0,0 +1,61 @@
+//go:build !integration
+
+package parser
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestSandboxMCPTrustedBotsSchema(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		value   any
+		wantErr bool
+	}{
+		{"one bot", []any{"github-actions[bot]"}, false},
+		{"multiple bots", []any{"github-actions[bot]", "copilot-swe-agent[bot]"}, false},
+		{"login without suffix", []any{"My-Bot_123"}, false},
+		{"empty list", []any{}, true},
+		{"empty identity", []any{""}, true},
+		{"command substitution", []any{"$(id)"}, true},
+		{"backtick substitution", []any{"`id`"}, true},
+		{"variable expansion", []any{"${HOME}"}, true},
+		{"workflow expression", []any{"${{ github.actor }}"}, true},
+		{"whitespace", []any{"my bot"}, true},
+		{"trailing newline", []any{"github-actions[bot]\n"}, true},
+		{"quote", []any{`my"bot`}, true},
+		{"backslash", []any{`my\bot`}, true},
+		{"non-ASCII identity", []any{"böt"}, true},
+		{"invalid suffix", []any{"my-bot[other]"}, true},
+		{"mixed types", []any{"github-actions[bot]", 42}, true},
+		{"scalar", "github-actions[bot]", true},
+		{"null", nil, true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			err := ValidateMainWorkflowFrontmatterWithSchemaAndLocation(map[string]any{
+				"on": "workflow_dispatch",
+				"sandbox": map[string]any{
+					"mcp": map[string]any{"trusted-bots": test.value},
+				},
+			}, "trusted-bots.md")
+			if test.wantErr {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+
+	t.Run("gateway JSON key is not a frontmatter alias", func(t *testing.T) {
+		err := ValidateMainWorkflowFrontmatterWithSchemaAndLocation(map[string]any{
+			"on": "workflow_dispatch",
+			"sandbox": map[string]any{
+				"mcp": map[string]any{"trustedBots": []any{"github-actions[bot]"}},
+			},
+		}, "trusted-bots.md")
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "trustedBots")
+	})
+}
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
@@ -4650,6 +4650,17 @@
                   "description": "Keepalive ping interval in seconds for HTTP MCP backends. Sends periodic pings to prevent session expiry during long-running agent tasks. Set to -1 to disable keepalive pings. Unset or 0 uses the gateway default (1500 seconds = 25 minutes).",
                   "minimum": -1,
                   "examples": [-1, 300, 600, 1500]
+                },
+                "trusted-bots": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "^[A-Za-z0-9_-]+(\\[bot\\])?$"
+                  },
+                  "description": "Additional GitHub bot identities merged with the MCP gateway's built-in trusted identities. Use only ASCII letters, digits, hyphens, or underscores, optionally followed by [bot]. Cannot remove or override built-in identities. Compiled to gateway.trustedBots in the gateway JSON configuration.",
+                  "examples": [["github-actions[bot]", "copilot-swe-agent[bot]"]]
                 }
               },
               "additionalProperties": false

diff --git a/pkg/workflow/frontmatter_extraction_security.go b/pkg/workflow/frontmatter_extraction_security.go
@@ -622,19 +622,14 @@ func (c *Compiler) extractMCPGatewayConfig(mcpVal any) *MCPGatewayRuntimeConfig
 		}
 	}
 
-	// Extract trustedBots / trusted-bots (additional bot identities to pass to the gateway)
-	for _, key := range []string{"trustedBots", "trusted-bots"} {
-		if trustedBotsVal, hasTrustedBots := mcpObj[key]; hasTrustedBots {
-			if trustedBotsSlice, ok := trustedBotsVal.([]any); ok {
-				for _, bot := range trustedBotsSlice {
-					if botStr, ok := bot.(string); ok {
-						mcpConfig.TrustedBots = append(mcpConfig.TrustedBots, botStr)
-					}
+	// Frontmatter uses trusted-bots; trustedBots is the generated gateway JSON field.
+	if trustedBotsVal, hasTrustedBots := mcpObj["trusted-bots"]; hasTrustedBots {
+		if trustedBotsSlice, ok := trustedBotsVal.([]any); ok {
+			for _, bot := range trustedBotsSlice {
+				if botStr, ok := bot.(string); ok {
+					mcpConfig.TrustedBots = append(mcpConfig.TrustedBots, botStr)
 				}
 			}
-			if len(mcpConfig.TrustedBots) > 0 {
-				break
-			}
 		}
 	}
 

diff --git a/pkg/workflow/frontmatter_extraction_security_test.go b/pkg/workflow/frontmatter_extraction_security_test.go
@@ -524,24 +524,24 @@ func TestExtractMCPGatewayConfigPayloadFields(t *testing.T) {
 func TestExtractMCPGatewayConfigTrustedBots(t *testing.T) {
 	compiler := &Compiler{}
 
-	t.Run("extracts trustedBots using camelCase key", func(t *testing.T) {
+	t.Run("does not extract gateway JSON camelCase key", func(t *testing.T) {
 		mcpObj := map[string]any{
 			"container":   "ghcr.io/github/gh-aw-mcpg",
 			"trustedBots": []any{"github-actions[bot]", "copilot-swe-agent[bot]"},
 		}
 		config := compiler.extractMCPGatewayConfig(mcpObj)
 		require.NotNil(t, config, "Should extract MCP gateway config")
-		assert.Equal(t, []string{"github-actions[bot]", "copilot-swe-agent[bot]"}, config.TrustedBots, "Should extract trustedBots")
+		assert.Nil(t, config.TrustedBots, "trustedBots is not a frontmatter field")
 	})
 
 	t.Run("extracts trustedBots using kebab-case key", func(t *testing.T) {
 		mcpObj := map[string]any{
 			"container":    "ghcr.io/github/gh-aw-mcpg",
-			"trusted-bots": []any{"github-actions[bot]"},
+			"trusted-bots": []any{"github-actions[bot]", "copilot-swe-agent[bot]", "my-bot"},
 		}
 		config := compiler.extractMCPGatewayConfig(mcpObj)
 		require.NotNil(t, config, "Should extract MCP gateway config")
-		assert.Equal(t, []string{"github-actions[bot]"}, config.TrustedBots, "Should extract trusted-bots")
+		assert.Equal(t, []string{"github-actions[bot]", "copilot-swe-agent[bot]", "my-bot"}, config.TrustedBots, "Should extract trusted-bots")
 	})
 
 	t.Run("leaves trustedBots nil when not specified", func(t *testing.T) {

diff --git a/pkg/workflow/mcp_gateway_reference_test.go b/pkg/workflow/mcp_gateway_reference_test.go
@@ -0,0 +1,60 @@
+//go:build !integration
+
+package workflow
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestMCPGatewayReferenceExamplesCompile(t *testing.T) {
+	pagePath := filepath.Join("..", "..", "docs", "src", "content", "docs", "reference", "mcp-gateway.md")
+	page, err := os.ReadFile(pagePath)
+	require.NoError(t, err)
+
+	for _, test := range []struct {
+		name string
+		want []string
+	}{
+		{
+			name: "trusted-bots",
+			want: []string{`"trustedBots": ["github-actions[bot]", "copilot-swe-agent[bot]"]`},
+		},
+		{
+			name: "oidc-mcp",
+			want: []string{
+				`"url": "https://my-server.example.com/mcp"`,
+				`"type": "github-oidc"`,
+				`"audience": "https://my-server.example.com"`,
+				"id-token: write",
+				"-e ACTIONS_ID_TOKEN_REQUEST_URL",
+				"-e ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+			},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			fence := "```aw wrap title=\".github/workflows/" + test.name + ".md\"\n"
+			require.Equal(t, 1, strings.Count(string(page), fence))
+			_, rest, found := strings.Cut(string(page), fence)
+			require.True(t, found)
+			example, _, found := strings.Cut(rest, "\n```")
+			require.True(t, found, "reference example must have a closing fence")
+
+			dir := t.TempDir()
+			path := filepath.Join(dir, test.name+".md")
+			require.NoError(t, os.WriteFile(path, []byte(example+"\n"), 0o600))
+			compiler := NewCompiler()
+			require.NoError(t, compiler.CompileWorkflow(path))
+
+			lock, err := os.ReadFile(filepath.Join(dir, test.name+".lock.yml"))
+			require.NoError(t, err)
+			for _, want := range test.want {
+				require.Contains(t, string(lock), want)
+			}
+		})
+	}
+}
diff --git a/pkg/workflow/mcp_renderer.go b/pkg/workflow/mcp_renderer.go
@@ -62,6 +62,9 @@ var mcpRendererLog = logger.New("workflow:mcp_renderer")
 // for built-in tool names and typical custom mcp-server keys.
 var safeMCPServerIDRE = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
 
+// Trusted bot identities are emitted into the same unquoted heredoc as server IDs.
+var safeMCPTrustedBotRE = regexp.MustCompile(`^[A-Za-z0-9_-]+(\[bot\])?$`)
+
 // isSafeMCPServerID reports whether id can be safely embedded inside an unquoted bash heredoc
 // without triggering shell expansion.
 func isSafeMCPServerID(id string) bool {
@@ -227,6 +230,9 @@ func RenderJSONMCPConfig( //nolint:largefunc // Existing renderer keeps MCP JSON
 		if len(options.GatewayConfig.TrustedBots) > 0 {
 			configBuilder.WriteString(",\n              \"trustedBots\": [")
 			for i, bot := range options.GatewayConfig.TrustedBots {
+				if !safeMCPTrustedBotRE.MatchString(bot) {
+					return fmt.Errorf("sandbox.mcp.trusted-bots: invalid identity %q; use only ASCII letters, digits, hyphens, or underscores, optionally followed by [bot] (for example, github-actions[bot])", bot)
+				}
 				if i > 0 {
 					configBuilder.WriteString(", ")
 				}