feat: parameterize tools.timeout and tools.startup-timeout to accept GitHub Actions expressions (#23888)

Author: Copilot

pkg/parser/schemas/main_workflow_schema.json

@@ -4029,15 +4029,34 @@
           ]
         },
         "timeout": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Timeout in seconds for tool/MCP server operations. Applies to all tools and MCP servers if supported by the engine. Default varies by engine (Claude: 60s, Codex: 120s).",
-          "examples": [60, 120, 300]
+          "description": "Timeout in seconds for tool/MCP server operations. Applies to all tools and MCP servers if supported by the engine. Default: 60 seconds (for both Claude and Codex). Supports GitHub Actions expressions for reusable workflow_call workflows.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 1,
+              "examples": [60, 120, 300]
+            },
+            {
+              "type": "string",
+              "description": "GitHub Actions expression (e.g. '${{ inputs.tool-timeout }}')",
+              "pattern": "^\\$\\{\\{.*\\}\\}$"
+            }
+          ]
         },
         "startup-timeout": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Timeout in seconds for MCP server startup. Applies to MCP server initialization if supported by the engine. Default: 120 seconds."
+          "description": "Timeout in seconds for MCP server startup. Applies to MCP server initialization if supported by the engine. Default: 120 seconds. Supports GitHub Actions expressions for reusable workflow_call workflows.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 1,
+              "examples": [30, 60, 120]
+            },
+            {
+              "type": "string",
+              "description": "GitHub Actions expression (e.g. '${{ inputs.startup-timeout }}')",
+              "pattern": "^\\$\\{\\{.*\\}\\}$"
+            }
+          ]
         },
         "serena": {
           "description": "REMOVED: Built-in support for Serena has been removed. Use the shared/mcp/serena.md workflow instead.",

pkg/workflow/claude_engine.go

@@ -399,15 +399,17 @@ func (e *ClaudeEngine) GetExecutionSteps(workflowData *WorkflowData, logFile str
 
 	// Set timeout environment variables for Claude Code
 	// Use tools.startup-timeout if specified, otherwise default to DefaultMCPStartupTimeout
+	// For expressions, fall back to default (can't compute ms value at compile time)
 	startupTimeoutMs := int(constants.DefaultMCPStartupTimeout / time.Millisecond)
-	if workflowData.ToolsStartupTimeout > 0 {
-		startupTimeoutMs = workflowData.ToolsStartupTimeout * 1000 // convert seconds to milliseconds
+	if n := templatableIntValue(&workflowData.ToolsStartupTimeout); n > 0 {
+		startupTimeoutMs = n * 1000 // convert seconds to milliseconds
 	}
 
 	// Use tools.timeout if specified, otherwise default to DefaultToolTimeout
+	// For expressions, fall back to default (can't compute ms value at compile time)
 	timeoutMs := int(constants.DefaultToolTimeout / time.Millisecond)
-	if workflowData.ToolsTimeout > 0 {
-		timeoutMs = workflowData.ToolsTimeout * 1000 // convert seconds to milliseconds
+	if n := templatableIntValue(&workflowData.ToolsTimeout); n > 0 {
+		timeoutMs = n * 1000 // convert seconds to milliseconds
 	}
 
 	env["MCP_TIMEOUT"] = strconv.Itoa(startupTimeoutMs)
@@ -419,13 +421,15 @@ func (e *ClaudeEngine) GetExecutionSteps(workflowData *WorkflowData, logFile str
 	applySafeOutputEnvToMap(env, workflowData)
 
 	// Add GH_AW_STARTUP_TIMEOUT environment variable (in seconds) if startup-timeout is specified
-	if workflowData.ToolsStartupTimeout > 0 {
-		env["GH_AW_STARTUP_TIMEOUT"] = strconv.Itoa(workflowData.ToolsStartupTimeout)
+	// Supports both literal integers and GitHub Actions expressions (e.g. "${{ inputs.startup-timeout }}")
+	if workflowData.ToolsStartupTimeout != "" {
+		env["GH_AW_STARTUP_TIMEOUT"] = workflowData.ToolsStartupTimeout
 	}
 
 	// Add GH_AW_TOOL_TIMEOUT environment variable (in seconds) if timeout is specified
-	if workflowData.ToolsTimeout > 0 {
-		env["GH_AW_TOOL_TIMEOUT"] = strconv.Itoa(workflowData.ToolsTimeout)
+	// Supports both literal integers and GitHub Actions expressions (e.g. "${{ inputs.tool-timeout }}")
+	if workflowData.ToolsTimeout != "" {
+		env["GH_AW_TOOL_TIMEOUT"] = workflowData.ToolsTimeout
 	}
 
 	if workflowData.EngineConfig != nil && workflowData.EngineConfig.MaxTurns != "" {

pkg/workflow/codex_engine.go

@@ -5,7 +5,6 @@ import (
 	"maps"
 	"regexp"
 	"sort"
-	"strconv"
 	"strings"
 
 	"github.com/github/gh-aw/pkg/constants"
@@ -332,13 +331,15 @@ mkdir -p "$CODEX_HOME/logs"
 	}
 
 	// Add GH_AW_STARTUP_TIMEOUT environment variable (in seconds) if startup-timeout is specified
-	if workflowData.ToolsStartupTimeout > 0 {
-		env["GH_AW_STARTUP_TIMEOUT"] = strconv.Itoa(workflowData.ToolsStartupTimeout)
+	// Supports both literal integers and GitHub Actions expressions (e.g. "${{ inputs.startup-timeout }}")
+	if workflowData.ToolsStartupTimeout != "" {
+		env["GH_AW_STARTUP_TIMEOUT"] = workflowData.ToolsStartupTimeout
 	}
 
 	// Add GH_AW_TOOL_TIMEOUT environment variable (in seconds) if timeout is specified
-	if workflowData.ToolsTimeout > 0 {
-		env["GH_AW_TOOL_TIMEOUT"] = strconv.Itoa(workflowData.ToolsTimeout)
+	// Supports both literal integers and GitHub Actions expressions (e.g. "${{ inputs.tool-timeout }}")
+	if workflowData.ToolsTimeout != "" {
+		env["GH_AW_TOOL_TIMEOUT"] = workflowData.ToolsTimeout
 	}
 
 	// Set the model environment variable.

pkg/workflow/compiler_orchestrator_tools.go

@@ -17,8 +17,8 @@ var orchestratorToolsLog = logger.New("workflow:compiler_orchestrator_tools")
 type toolsProcessingResult struct {
 	tools                 map[string]any
 	runtimes              map[string]any
-	toolsTimeout          int
-	toolsStartupTimeout   int
+	toolsTimeout          string
+	toolsStartupTimeout   string
 	markdownContent       string
 	importedMarkdown      string   // Only imports WITH inputs (for compile-time substitution)
 	importPaths           []string // Import paths for runtime-import macro generation (imports without inputs)

pkg/workflow/compiler_orchestrator_tools_test.go

@@ -252,7 +252,7 @@ tools:
 	require.NoError(t, err)
 	require.NotNil(t, result)
 
-	assert.Equal(t, 600, result.toolsTimeout, "Tools timeout should be extracted")
+	assert.Equal(t, "600", result.toolsTimeout, "Tools timeout should be extracted")
 }
 
 // TestProcessToolsAndMarkdown_StartupTimeout tests startup timeout extraction
@@ -296,7 +296,7 @@ tools:
 	require.NoError(t, err)
 	require.NotNil(t, result)
 
-	assert.Equal(t, 120, result.toolsStartupTimeout, "Startup timeout should be extracted")
+	assert.Equal(t, "120", result.toolsStartupTimeout, "Startup timeout should be extracted")
 }
 
 // TestProcessToolsAndMarkdown_InvalidTimeout tests invalid timeout values

pkg/workflow/compiler_orchestrator_workflow_test.go

@@ -38,8 +38,8 @@ func TestBuildInitialWorkflowData_BasicFields(t *testing.T) {
 		markdownContent:      "Full markdown content",
 		tools:                map[string]any{"bash": []string{"echo"}},
 		runtimes:             map[string]any{"node": "18"},
-		toolsTimeout:         300,
-		toolsStartupTimeout:  60,
+		toolsTimeout:         "300",
+		toolsStartupTimeout:  "60",
 		needsTextOutput:      true,
 		safeOutputs:          &SafeOutputsConfig{},
 		secretMasking:        &SecretMaskingConfig{},
@@ -80,8 +80,8 @@ func TestBuildInitialWorkflowData_BasicFields(t *testing.T) {
 	assert.NotNil(t, workflowData.ParsedTools)
 	assert.NotNil(t, workflowData.NetworkPermissions)
 	assert.NotNil(t, workflowData.SandboxConfig)
-	assert.Equal(t, 300, workflowData.ToolsTimeout)
-	assert.Equal(t, 60, workflowData.ToolsStartupTimeout)
+	assert.Equal(t, "300", workflowData.ToolsTimeout)
+	assert.Equal(t, "60", workflowData.ToolsStartupTimeout)
 	assert.True(t, workflowData.NeedsTextOutput)
 	assert.Equal(t, "agent.md", workflowData.AgentFile)
 }
@@ -1396,8 +1396,8 @@ func TestBuildInitialWorkflowData_FieldMapping(t *testing.T) {
 		workflowName:         "Test Name",
 		frontmatterName:      "Frontmatter Name",
 		trackerID:            "TRK-001",
-		toolsTimeout:         500,
-		toolsStartupTimeout:  100,
+		toolsTimeout:         "500",
+		toolsStartupTimeout:  "100",
 		needsTextOutput:      true,
 		markdownContent:      "# Content",
 		importedMarkdown:     "Imported",
@@ -1428,8 +1428,8 @@ func TestBuildInitialWorkflowData_FieldMapping(t *testing.T) {
 	assert.Equal(t, "Test Name", workflowData.Name)
 	assert.Equal(t, "Frontmatter Name", workflowData.FrontmatterName)
 	assert.Equal(t, "TRK-001", workflowData.TrackerID)
-	assert.Equal(t, 500, workflowData.ToolsTimeout)
-	assert.Equal(t, 100, workflowData.ToolsStartupTimeout)
+	assert.Equal(t, "500", workflowData.ToolsTimeout)
+	assert.Equal(t, "100", workflowData.ToolsStartupTimeout)
 	assert.True(t, workflowData.NeedsTextOutput)
 	assert.Equal(t, "# Content", workflowData.MarkdownContent)
 	assert.Equal(t, "Imported", workflowData.ImportedMarkdown)

pkg/workflow/compiler_types.go

@@ -416,8 +416,8 @@ type WorkflowData struct {
 	RepoMemoryConfig            *RepoMemoryConfig         // parsed repo-memory configuration
 	QmdConfig                   *QmdToolConfig            // parsed qmd tool configuration (docs globs)
 	Runtimes                    map[string]any            // runtime version overrides from frontmatter
-	ToolsTimeout                int                       // timeout in seconds for tool/MCP operations (0 = use engine default)
-	ToolsStartupTimeout         int                       // timeout in seconds for MCP server startup (0 = use engine default)
+	ToolsTimeout                string                    // timeout for tool/MCP operations: numeric string (seconds) or GitHub Actions expression (empty = use engine default)
+	ToolsStartupTimeout         string                    // timeout for MCP server startup: numeric string (seconds) or GitHub Actions expression (empty = use engine default)
 	Features                    map[string]any            // feature flags and configuration options from frontmatter (supports bool and string values)
 	ActionCache                 *ActionCache              // cache for action pin resolutions
 	ActionResolver              *ActionResolver           // resolver for action pins

pkg/workflow/copilot_engine_execution.go

@@ -309,13 +309,15 @@ COPILOT_CLI_INSTRUCTION="$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"
 	applySafeOutputEnvToMap(env, workflowData)
 
 	// Add GH_AW_STARTUP_TIMEOUT environment variable (in seconds) if startup-timeout is specified
-	if workflowData.ToolsStartupTimeout > 0 {
-		env["GH_AW_STARTUP_TIMEOUT"] = strconv.Itoa(workflowData.ToolsStartupTimeout)
+	// Supports both literal integers and GitHub Actions expressions (e.g. "${{ inputs.startup-timeout }}")
+	if workflowData.ToolsStartupTimeout != "" {
+		env["GH_AW_STARTUP_TIMEOUT"] = workflowData.ToolsStartupTimeout
 	}
 
 	// Add GH_AW_TOOL_TIMEOUT environment variable (in seconds) if timeout is specified
-	if workflowData.ToolsTimeout > 0 {
-		env["GH_AW_TOOL_TIMEOUT"] = strconv.Itoa(workflowData.ToolsTimeout)
+	// Supports both literal integers and GitHub Actions expressions (e.g. "${{ inputs.tool-timeout }}")
+	if workflowData.ToolsTimeout != "" {
+		env["GH_AW_TOOL_TIMEOUT"] = workflowData.ToolsTimeout
 	}
 
 	if workflowData.EngineConfig != nil && workflowData.EngineConfig.MaxTurns != "" {

pkg/workflow/frontmatter_extraction_metadata.go

@@ -3,6 +3,7 @@ package workflow
 import (
 	"fmt"
 	"maps"
+	"strconv"
 	"strings"
 
 	"github.com/github/gh-aw/pkg/logger"
@@ -144,18 +145,27 @@ func buildSourceURL(source string) string {
 }
 
 // extractToolsTimeout extracts the timeout setting from tools
-// Returns 0 if not set (engines will use their own defaults)
-// Returns error if timeout is explicitly set but invalid (< 1)
-func (c *Compiler) extractToolsTimeout(tools map[string]any) (int, error) {
+// Returns "" if not set (engines will use their own defaults)
+// Returns error if timeout is explicitly set but invalid (< 1 for literals, or non-expression string)
+func (c *Compiler) extractToolsTimeout(tools map[string]any) (string, error) {
 	if tools == nil {
-		return 0, nil // Use engine defaults
+		return "", nil // Use engine defaults
 	}
 
 	// Check if timeout is explicitly set in tools
 	if timeoutValue, exists := tools["timeout"]; exists {
 		frontmatterMetadataLog.Printf("Extracting tools.timeout value: type=%T", timeoutValue)
-		var timeout int
+		// Handle GitHub Actions expression strings
+		if strVal, ok := timeoutValue.(string); ok {
+			if isExpressionString(strVal) {
+				frontmatterMetadataLog.Printf("Extracted tools.timeout as expression: %s", strVal)
+				return strVal, nil
+			}
+			frontmatterMetadataLog.Printf("Invalid tools.timeout string (not an expression): %s", strVal)
+			return "", fmt.Errorf("tools.timeout must be an integer or a GitHub Actions expression (e.g. '${{ inputs.tool-timeout }}'), got string %q", strVal)
+		}
 		// Handle different numeric types with safe conversions to prevent overflow
+		var timeout int
 		switch v := timeoutValue.(type) {
 		case int:
 			timeout = v
@@ -169,33 +179,40 @@ func (c *Compiler) extractToolsTimeout(tools map[string]any) (int, error) {
 			timeout = int(v)
 		default:
 			frontmatterMetadataLog.Printf("Invalid tools.timeout type: %T", timeoutValue)
-			return 0, fmt.Errorf("tools.timeout must be an integer, got %T", timeoutValue)
+			return "", fmt.Errorf("tools.timeout must be an integer or a GitHub Actions expression, got %T", timeoutValue)
 		}
 
 		// Validate minimum value per schema constraint
 		if timeout < 1 {
 			frontmatterMetadataLog.Printf("Invalid tools.timeout value: %d (must be >= 1)", timeout)
-			return 0, fmt.Errorf("tools.timeout must be at least 1 second, got %d. Example:\ntools:\n  timeout: 60", timeout)
+			return "", fmt.Errorf("tools.timeout must be at least 1 second, got %d. Example:\ntools:\n  timeout: 60", timeout)
 		}
 
 		frontmatterMetadataLog.Printf("Extracted tools.timeout: %d seconds", timeout)
-		return timeout, nil
+		return strconv.Itoa(timeout), nil
 	}
 
-	// Default to 0 (use engine defaults)
-	return 0, nil
+	// Default to "" (use engine defaults)
+	return "", nil
 }
 
 // extractToolsStartupTimeout extracts the startup-timeout setting from tools
-// Returns 0 if not set (engines will use their own defaults)
-// Returns error if startup-timeout is explicitly set but invalid (< 1)
-func (c *Compiler) extractToolsStartupTimeout(tools map[string]any) (int, error) {
+// Returns "" if not set (engines will use their own defaults)
+// Returns error if startup-timeout is explicitly set but invalid (< 1 for literals, or non-expression string)
+func (c *Compiler) extractToolsStartupTimeout(tools map[string]any) (string, error) {
 	if tools == nil {
-		return 0, nil // Use engine defaults
+		return "", nil // Use engine defaults
 	}
 
 	// Check if startup-timeout is explicitly set in tools
 	if timeoutValue, exists := tools["startup-timeout"]; exists {
+		// Handle GitHub Actions expression strings
+		if strVal, ok := timeoutValue.(string); ok {
+			if isExpressionString(strVal) {
+				return strVal, nil
+			}
+			return "", fmt.Errorf("tools.startup-timeout must be an integer or a GitHub Actions expression (e.g. '${{ inputs.startup-timeout }}'), got string %q", strVal)
+		}
 		var timeout int
 		// Handle different numeric types with safe conversions to prevent overflow
 		switch v := timeoutValue.(type) {
@@ -210,19 +227,19 @@ func (c *Compiler) extractToolsStartupTimeout(tools map[string]any) (int, error)
 		case float64:
 			timeout = int(v)
 		default:
-			return 0, fmt.Errorf("tools.startup-timeout must be an integer, got %T", timeoutValue)
+			return "", fmt.Errorf("tools.startup-timeout must be an integer or a GitHub Actions expression, got %T", timeoutValue)
 		}
 
 		// Validate minimum value per schema constraint
 		if timeout < 1 {
-			return 0, fmt.Errorf("tools.startup-timeout must be at least 1 second, got %d. Example:\ntools:\n  startup-timeout: 120", timeout)
+			return "", fmt.Errorf("tools.startup-timeout must be at least 1 second, got %d. Example:\ntools:\n  startup-timeout: 120", timeout)
 		}
 
-		return timeout, nil
+		return strconv.Itoa(timeout), nil
 	}
 
-	// Default to 0 (use engine defaults)
-	return 0, nil
+	// Default to "" (use engine defaults)
+	return "", nil
 }
 
 // extractToolsFromFrontmatter extracts tools section from frontmatter map