Address blocking review comments for MCP gateway agent ID migration

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Author: Copilot

actions/setup/sh/check_mcp_servers.sh

@@ -37,7 +37,7 @@ print_timing() {
 #   1 - Invalid arguments, configuration file issues, no successful connections, or required server failures
 
 if [ "$#" -ne 3 ]; then
-  echo "Usage: $0 GATEWAY_CONFIG_PATH GATEWAY_URL GATEWAY_API_KEY" >&2
+  echo "Usage: $0 GATEWAY_CONFIG_PATH GATEWAY_URL GATEWAY_AGENT_ID" >&2
   exit 1
 fi
 

docs/public/editor/autocomplete-data.json

@@ -905,6 +905,11 @@
               "enum": [true, false],
               "leaf": true
             },
+            "ca-cert": {
+              "type": "string",
+              "desc": "Host path to an additional CA certificate for API proxy upstream TLS verification.",
+              "leaf": true
+            },
             "runtime": {
               "type": "string",
               "desc": "Sandbox runtime profile for the agent container.",
@@ -1042,9 +1047,9 @@
               "desc": "Port number for the MCP gateway HTTP server (default: 8080)",
               "leaf": true
             },
-            "api-key": {
+            "agent-id": {
               "type": "string",
-              "desc": "API key for authenticating with the MCP gateway (supports ${{ secrets.* }} syntax)",
+              "desc": "Agent/session identifier for authenticating with the MCP gateway (supports ${{ secrets.* }} syntax)",
               "leaf": true
             },
             "domain": {

docs/src/content/docs/reference/frontmatter-full.md

@@ -566,6 +566,18 @@ on:
     branches-ignore: []
       # Array of strings
 
+    # Filter by workflow run conclusion (for example, failure). Compiled into a
+    # guarded if: condition.
+    # (optional)
+    # Accepted formats:
+
+    # Format 1: string
+    conclusion: "success"
+
+    # Format 2: array
+    conclusion: []
+      # Array items: string
+
   # Release event trigger
   # (optional)
   release:
@@ -1547,10 +1559,11 @@ on:
 
 # ⚠️ Experimental. Agent Plugins to install after the agentic engine. Each GitHub
 # repository reference must include a ref that the compiler resolves to a commit
-# SHA. Using this field emits a compile-time warning.
+# SHA. Using this field emits a compile-time warning. Entries may also be objects
+# to configure per-plugin authentication via github-token or github-app, for
+# installing plugins from private repositories.
 # (optional)
 plugins: []
-  # Array of A plugin repository reference in owner/repository[/path]@ref format
 
 # GitHub token permissions for the workflow. Controls what the GITHUB_TOKEN can
 # access during execution. Use the principle of least privilege - only grant the
@@ -2260,6 +2273,12 @@ sandbox:
     # (optional)
     token-steering: true
 
+    # Host path to an additional CA certificate for API proxy upstream TLS
+    # verification. The file is bind-mounted read-only into the API proxy sidecar.
+    # Maps to apiProxy.caCert; requires AWF v0.28.10 or later.
+    # (optional)
+    ca-cert: "example-value"
+
     # Sandbox runtime profile for the agent container. Each value selects one
     # supported security and topology profile: 'docker' (default) runs the agent under
     # Docker with a rootless AWF and network isolation; 'docker-sudo-iptables' runs
@@ -2434,10 +2453,10 @@ sandbox:
     # (optional)
     port: 1
 
-    # API key for authenticating with the MCP gateway (supports ${{ secrets.* }}
-    # syntax)
+    # Agent/session identifier for authenticating with the MCP gateway (supports ${{
+    # secrets.* }} syntax)
     # (optional)
-    api-key: "example-value"
+    agent-id: "example-value"
 
     # Gateway domain for URL generation (default: 'host.docker.internal' when agent is
     # enabled, 'localhost' when disabled)
@@ -4072,10 +4091,17 @@ tools:
     # Integration mode: 'cli' (recommended) installs @playwright/cli via npm for
     # token-efficient CLI invocations — use playwright-cli commands in bash and
     # localhost to reach local servers; 'mcp' (deprecated) runs a Docker-based MCP
-    # server.
+    # server. Must be a literal value; GitHub Actions expressions are rejected.
     # (optional)
+    # Accepted formats:
+
+    # Format 1: string
     mode: "cli"
 
+    # Format 2: Not allowed at runtime: mode must be a literal 'cli' or 'mcp' value,
+    # not a GitHub Actions expression.
+    mode: "example-value"
+
   # GitHub Agentic Workflows MCP server for workflow introspection and analysis.
   # Provides tools for checking status, compiling workflows, downloading logs, and
   # auditing runs.

pkg/workflow/codex_engine_test.go

@@ -455,7 +455,7 @@ func TestCodexEngineRenderMCPConfig(t *testing.T) {
 				"\"gateway\": {",
 				"\"port\": $MCP_GATEWAY_PORT,",
 				"\"domain\": \"${MCP_GATEWAY_DOMAIN}\",",
-				"\"apiKey\": \"${MCP_GATEWAY_AGENT_ID}\",",
+				"\"agentId\": \"${MCP_GATEWAY_AGENT_ID}\",",
 				"\"payloadDir\": \"${MCP_GATEWAY_PAYLOAD_DIR}\",",
 				"\"startupTimeout\": 120",
 				"}",

pkg/workflow/mcp_gateway_env_security_test.go

@@ -12,7 +12,7 @@ import (
 )
 
 func writeMCPGatewayStepEnvForTest(yaml *strings.Builder, mcpEnvVars map[string]string, safeOutputsInputEnvVars map[string]string, gatewayEnvVars map[string]string) {
-	writeMCPGatewayStepEnvWithCustomGatewayEnvNames(yaml, mcpEnvVars, safeOutputsInputEnvVars, gatewayEnvVars, sanitizedGatewayEnvNames(gatewayEnvVars))
+	writeMCPGatewayStepEnvWithCustomGatewayEnvNames(yaml, mcpEnvVars, safeOutputsInputEnvVars, gatewayEnvVars, sanitizedGatewayEnvNames(gatewayEnvVars), "")
 }
 
 func appendMCPGatewayCustomAndHTTPEnvFlagsForTest(containerCmd *strings.Builder, workflowData *WorkflowData, gatewayConfig *MCPGatewayRuntimeConfig, mcpEnvVars map[string]string, hasGitHub bool, githubTool map[string]any, tools map[string]any, engine CodingAgentEngine) {
@@ -233,3 +233,25 @@ func TestMCPGatewayFilteredCustomEnvDoesNotSuppressHTTPMCPEnvForwarding(t *testi
 
 	assert.Equal(t, " -e GH_AW_MCP_GATEWAY_ENV_0", containerCommand.String())
 }
+
+func TestMCPGatewayConfiguredAgentIDPassedViaStepEnv(t *testing.T) {
+	configuredAgentID := `my-agent-id"; touch /tmp/pwned; #`
+
+	var stepEnv strings.Builder
+	writeMCPGatewayStepEnvWithCustomGatewayEnvNames(&stepEnv, nil, nil, nil, nil, configuredAgentID)
+
+	assert.Contains(t, stepEnv.String(), `GH_AW_MCP_GATEWAY_CONFIGURED_AGENT_ID: "my-agent-id\"; touch /tmp/pwned; #"`)
+
+	var runScript strings.Builder
+	writeMCPGatewayExports(&runScript, writeMCPGatewayExportsOptions{
+		engine:        NewCopilotEngine(),
+		workflowData:  &WorkflowData{},
+		gatewayConfig: &MCPGatewayRuntimeConfig{AgentID: configuredAgentID},
+		port:          8080,
+		domain:        "localhost",
+		payloadDir:    "/tmp/payloads",
+	})
+
+	assert.Contains(t, runScript.String(), `export MCP_GATEWAY_AGENT_ID="${GH_AW_MCP_GATEWAY_CONFIGURED_AGENT_ID}"`)
+	assert.NotContains(t, runScript.String(), `export MCP_GATEWAY_AGENT_ID="my-agent-id`)
+}

pkg/workflow/mcp_setup_gateway.go

@@ -18,6 +18,7 @@ const mcpGatewayCustomEnvNamesVar = "GH_AW_MCP_GATEWAY_CUSTOM_ENV_NAMES"
 const mcpGatewayCustomEnvTransportPrefix = "GH_AW_MCP_GATEWAY_ENV_"
 const mcpGatewayReservedEnvPrefix = "GH_AW_MCP_GATEWAY_"
 const mcpGatewayCustomEnvMarker = "__GH_AW_MCP_GATEWAY_CUSTOM_ENV__"
+const mcpGatewayConfiguredAgentIDVar = "GH_AW_MCP_GATEWAY_CONFIGURED_AGENT_ID"
 
 var optionalPRHeadEnvVars = []string{
 	"GH_AW_PR_HEAD_BASE_BRANCH",
@@ -46,7 +47,7 @@ func generateMCPGatewaySetup(yaml *strings.Builder, tools map[string]any, mcpToo
 	gatewayConfig := workflowData.SandboxConfig.MCP
 	mcpEnvVars := collectMCPEnvironmentVariables(tools, mcpTools, workflowData, hasAgenticWorkflows)
 	customGatewayEnvNames := sanitizedGatewayEnvNames(gatewayConfig.Env)
-	writeMCPGatewayStepEnvWithCustomGatewayEnvNames(yaml, mcpEnvVars, safeOutputsInputEnvVars, gatewayConfig.Env, customGatewayEnvNames)
+	writeMCPGatewayStepEnvWithCustomGatewayEnvNames(yaml, mcpEnvVars, safeOutputsInputEnvVars, gatewayConfig.Env, customGatewayEnvNames, gatewayConfig.AgentID)
 	yaml.WriteString("        run: |\n")
 	yaml.WriteString("          set -eo pipefail\n")
 	yaml.WriteString("          mkdir -p \"${RUNNER_TEMP}/gh-aw/mcp-config\"\n")
@@ -101,8 +102,8 @@ func generateMCPGatewaySetup(yaml *strings.Builder, tools map[string]any, mcpToo
 	return engine.RenderMCPConfig(yaml, tools, mcpTools, workflowData)
 }
 
-func writeMCPGatewayStepEnvWithCustomGatewayEnvNames(yaml *strings.Builder, mcpEnvVars map[string]string, safeOutputsInputEnvVars map[string]string, gatewayEnvVars map[string]string, customEnvVarNames []string) {
-	if len(mcpEnvVars) == 0 && len(safeOutputsInputEnvVars) == 0 && len(customEnvVarNames) == 0 {
+func writeMCPGatewayStepEnvWithCustomGatewayEnvNames(yaml *strings.Builder, mcpEnvVars map[string]string, safeOutputsInputEnvVars map[string]string, gatewayEnvVars map[string]string, customEnvVarNames []string, configuredAgentID string) {
+	if len(mcpEnvVars) == 0 && len(safeOutputsInputEnvVars) == 0 && len(customEnvVarNames) == 0 && configuredAgentID == "" {
 		return
 	}
 	yaml.WriteString("        env:\n")
@@ -148,6 +149,9 @@ func writeMCPGatewayStepEnvWithCustomGatewayEnvNames(yaml *strings.Builder, mcpE
 			yaml.WriteString(formatYAMLEnv("          ", mcpGatewayCustomEnvTransportName(i), gatewayEnvVars[envVarName]))
 		}
 	}
+	if configuredAgentID != "" {
+		yaml.WriteString(formatYAMLEnv("          ", mcpGatewayConfiguredAgentIDVar, configuredAgentID))
+	}
 }
 
 // sanitizedGatewayEnvNames returns the sorted subset of user-supplied gateway
@@ -272,7 +276,7 @@ func writeMCPGatewayExports(yaml *strings.Builder, opts writeMCPGatewayExportsOp
 		yaml.WriteString("          echo \"::add-mask::${MCP_GATEWAY_AGENT_ID}\"\n")
 		yaml.WriteString("          export MCP_GATEWAY_AGENT_ID\n")
 	} else {
-		yaml.WriteString("          export MCP_GATEWAY_AGENT_ID=\"" + gatewayConfig.AgentID + "\"\n")
+		yaml.WriteString("          export MCP_GATEWAY_AGENT_ID=\"${" + mcpGatewayConfiguredAgentIDVar + "}\"\n")
 		yaml.WriteString("          echo \"::add-mask::${MCP_GATEWAY_AGENT_ID}\"\n")
 	}
 	yaml.WriteString("          export MCP_GATEWAY_PAYLOAD_DIR=\"" + payloadDir + "\"\n")