Replace hardcoded /opt/gh-aw paths with dynamic GH_AW_HOME expressions

- Add GhAwHome, GhAwHomeJS, GhAwHomeExpr, GhAwHomeExprDefault constants
- Add JsRequireGhAw() helper for JS require() expressions
- Update SetupActionDestination to use GhAwHomeExpr
- Add GhAwHomeDefault constant to pkg/constants
- Update DefaultGhAwMount to use shell expansion
- Add GH_AW_HOME to job-level env in agent, safe-outputs, conclusion,
  push_repo_memory, and update_cache_memory jobs
- Replace all hardcoded /opt/gh-aw paths in 30+ source files
- Update test assertions to match new dynamic path expressions
- Fix insertIndex calculation in compiler_safe_outputs_job.go to use
  hasCustomTokenSafeOutputs() for accurate line counting

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Copilot

pkg/constants/constants.go

@@ -435,9 +435,13 @@ const DefaultAlpineImage = "alpine:latest"
 // This image is built during workflow execution and includes the gh-aw binary and dependencies
 const DevModeGhAwImage = "localhost/gh-aw:dev"
 
+// GhAwHomeDefault is the default value for GH_AW_HOME when the env var is not set
+const GhAwHomeDefault = "/opt/gh-aw"
+
 // DefaultGhAwMount is the mount path for the gh-aw directory in containerized MCP servers
-// The gh-aw binary and supporting files are mounted read-only from /opt/gh-aw
-const DefaultGhAwMount = "/opt/gh-aw:/opt/gh-aw:ro"
+// Uses shell expansion so docker gets the resolved path at runtime.
+// GH_AW_HOME is always set in the job-level env, so no fallback is needed here.
+const DefaultGhAwMount = "\\${GH_AW_HOME}:\\${GH_AW_HOME}:ro"
 
 // DefaultGhBinaryMount is the mount path for the gh CLI binary in containerized MCP servers
 // The gh CLI is required for agentic-workflows MCP server to run gh commands

pkg/workflow/agentic_output_test.go

@@ -62,8 +62,8 @@ This workflow tests the agentic output collection functionality.
 	lockContent := string(content)
 
 	// Verify GH_AW_SAFE_OUTPUTS is set at job level with fixed path
-	if !strings.Contains(lockContent, "GH_AW_SAFE_OUTPUTS: /opt/gh-aw/safeoutputs/outputs.jsonl") {
-		t.Error("Expected 'GH_AW_SAFE_OUTPUTS: /opt/gh-aw/safeoutputs/outputs.jsonl' environment variable in generated workflow")
+	if !strings.Contains(lockContent, "GH_AW_SAFE_OUTPUTS: "+GhAwHomeExpr+"/safeoutputs/outputs.jsonl") {
+		t.Error("Expected 'GH_AW_SAFE_OUTPUTS: " + GhAwHomeExpr + "/safeoutputs/outputs.jsonl' environment variable in generated workflow")
 	}
 
 	if !strings.Contains(lockContent, "- name: Ingest agent output") {
@@ -171,8 +171,8 @@ This workflow tests that Codex engine gets GH_AW_SAFE_OUTPUTS but not engine out
 	lockContent := string(content)
 
 	// Verify that Codex workflow DOES have GH_AW_SAFE_OUTPUTS functionality at job level
-	if !strings.Contains(lockContent, "GH_AW_SAFE_OUTPUTS: /opt/gh-aw/safeoutputs/outputs.jsonl") {
-		t.Error("Codex workflow should have 'GH_AW_SAFE_OUTPUTS: /opt/gh-aw/safeoutputs/outputs.jsonl' environment variable (GH_AW_SAFE_OUTPUTS functionality)")
+	if !strings.Contains(lockContent, "GH_AW_SAFE_OUTPUTS: "+GhAwHomeExpr+"/safeoutputs/outputs.jsonl") {
+		t.Error("Codex workflow should have 'GH_AW_SAFE_OUTPUTS: " + GhAwHomeExpr + "/safeoutputs/outputs.jsonl' environment variable (GH_AW_SAFE_OUTPUTS functionality)")
 	}
 
 	if !strings.Contains(lockContent, "- name: Ingest agent output") {

pkg/workflow/agentic_workflow_test.go

@@ -162,8 +162,8 @@ func TestAgenticWorkflowsInstallStepIncludesGHToken(t *testing.T) {
 		"install step should include command to verify gh-aw installation")
 
 	// Verify the binary copy command is present for MCP server containerization
-	assert.Contains(t, result, "cp \"$GH_AW_BIN\" /opt/gh-aw/gh-aw",
-		"install step should copy gh-aw binary to /opt/gh-aw for MCP server containerization")
+	assert.Contains(t, result, "cp \"$GH_AW_BIN\" "+GhAwHome+"/gh-aw",
+		"install step should copy gh-aw binary to "+GhAwHome+" for MCP server containerization")
 }
 
 func TestAgenticWorkflowsInstallStepSkippedWithImport(t *testing.T) {

pkg/workflow/aw_info_tmp_test.go

@@ -56,7 +56,7 @@ This workflow tests that aw_info.json is generated in /tmp directory.
 	lockStr := string(lockContent)
 
 	// Test 1: Verify the step uses the generate_aw_info.cjs module
-	if !strings.Contains(lockStr, "require('/opt/gh-aw/actions/generate_aw_info.cjs')") {
+	if !strings.Contains(lockStr, "require("+JsRequireGhAw("actions/generate_aw_info.cjs")+")") {
 		t.Error("Expected step to require generate_aw_info.cjs module")
 	}
 

pkg/workflow/cache.go

@@ -360,7 +360,7 @@ func generateCacheMemorySteps(builder *strings.Builder, data *WorkflowData) {
 		if useBackwardCompatiblePaths {
 			// For single default cache, use the original directory for backward compatibility
 			builder.WriteString("      - name: Create cache-memory directory\n")
-			builder.WriteString("        run: bash /opt/gh-aw/actions/create_cache_memory_dir.sh\n")
+			builder.WriteString("        run: bash " + GhAwHome + "/actions/create_cache_memory_dir.sh\n")
 		} else {
 			fmt.Fprintf(builder, "      - name: Create cache-memory directory (%s)\n", cache.ID)
 			builder.WriteString("        run: |\n")
@@ -498,9 +498,9 @@ func generateCacheMemoryValidation(builder *strings.Builder, data *WorkflowData)
 
 		// Build validation script
 		var validationScript strings.Builder
-		validationScript.WriteString("            const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');\n")
+		validationScript.WriteString("            const { setupGlobals } = require(" + JsRequireGhAw("actions/setup_globals.cjs") + ");\n")
 		validationScript.WriteString("            setupGlobals(core, github, context, exec, io);\n")
-		validationScript.WriteString("            const { validateMemoryFiles } = require('/opt/gh-aw/actions/validate_memory_files.cjs');\n")
+		validationScript.WriteString("            const { validateMemoryFiles } = require(" + JsRequireGhAw("actions/validate_memory_files.cjs") + ");\n")
 		fmt.Fprintf(&validationScript, "            const allowedExtensions = %s;\n", allowedExtsJSON)
 		fmt.Fprintf(&validationScript, "            const result = validateMemoryFiles('%s', 'cache', allowedExtensions);\n", cacheDir)
 		validationScript.WriteString("            if (!result.valid) {\n")
@@ -770,9 +770,9 @@ func (c *Compiler) buildUpdateCacheMemoryJob(data *WorkflowData, threatDetection
 
 			// Build validation script
 			var validationScript strings.Builder
-			validationScript.WriteString("            const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');\n")
+			validationScript.WriteString("            const { setupGlobals } = require(" + JsRequireGhAw("actions/setup_globals.cjs") + ");\n")
 			validationScript.WriteString("            setupGlobals(core, github, context, exec, io);\n")
-			validationScript.WriteString("            const { validateMemoryFiles } = require('/opt/gh-aw/actions/validate_memory_files.cjs');\n")
+			validationScript.WriteString("            const { validateMemoryFiles } = require(" + JsRequireGhAw("actions/validate_memory_files.cjs") + ");\n")
 			fmt.Fprintf(&validationScript, "            const allowedExtensions = %s;\n", allowedExtsJSON)
 			fmt.Fprintf(&validationScript, "            const result = validateMemoryFiles('%s', 'cache', allowedExtensions);\n", cacheDir)
 			validationScript.WriteString("            if (!result.valid) {\n")
@@ -844,11 +844,11 @@ func (c *Compiler) buildUpdateCacheMemoryJob(data *WorkflowData, threatDetection
 	}
 
 	// Set GH_AW_WORKFLOW_ID_SANITIZED so cache keys match those used in the agent job
-	var jobEnv map[string]string
+	jobEnv := map[string]string{
+		"GH_AW_HOME": GhAwHomeExprDefault,
+	}
 	if data.WorkflowID != "" {
-		jobEnv = map[string]string{
-			"GH_AW_WORKFLOW_ID_SANITIZED": SanitizeWorkflowIDForCacheKey(data.WorkflowID),
-		}
+		jobEnv["GH_AW_WORKFLOW_ID_SANITIZED"] = SanitizeWorkflowIDForCacheKey(data.WorkflowID)
 	}
 
 	job := &Job{

pkg/workflow/cache_memory_integration_test.go

@@ -42,7 +42,7 @@ tools:
 				"uses: actions/cache@",
 				"key: memory-${{ env.GH_AW_WORKFLOW_ID_SANITIZED }}-${{ github.run_id }}",
 				"path: /tmp/gh-aw/cache-memory",
-				"cat \"/opt/gh-aw/prompts/cache_memory_prompt.md\"",
+				"cat \"" + GhAwHome + "/prompts/cache_memory_prompt.md\"",
 				"GH_AW_CACHE_DIR: '/tmp/gh-aw/cache-memory/'",
 				"GH_AW_CACHE_DIR: process.env.GH_AW_CACHE_DIR",
 			},

pkg/workflow/codex_engine_test.go

@@ -208,7 +208,7 @@ func TestCodexEngineRenderMCPConfig(t *testing.T) {
 				"GH_AW_MCP_CONFIG_EOF",
 				"",
 				"# Generate JSON config for MCP gateway",
-				"cat << GH_AW_MCP_CONFIG_EOF | bash /opt/gh-aw/actions/start_mcp_gateway.sh",
+				"cat << GH_AW_MCP_CONFIG_EOF | bash " + GhAwHome + "/actions/start_mcp_gateway.sh",
 				"{",
 				"\"mcpServers\": {",
 				"\"github\": {",

pkg/workflow/compiler_custom_actions_test.go

@@ -247,7 +247,7 @@ Test workflow with script mode.
 	}
 
 	// 5. Setup step should have INPUT_DESTINATION environment variable
-	if !strings.Contains(lockStr, "INPUT_DESTINATION: /opt/gh-aw/actions") {
+	if !strings.Contains(lockStr, "INPUT_DESTINATION: "+SetupActionDestination) {
 		t.Error("Expected INPUT_DESTINATION environment variable in setup step for script mode")
 	}
 

pkg/workflow/compiler_main_job.go

@@ -174,24 +174,23 @@ func (c *Compiler) buildMainJob(data *WorkflowData, activationJobCreated bool) (
 		}
 	}
 
-	// Build job-level environment variables for safe outputs
-	var env map[string]string
-	if data.SafeOutputs != nil {
-		env = make(map[string]string)
+	// Build job-level environment variables
+	// Use GhAwHomeExprDefault so callers can override GH_AW_HOME via workflow/repo env
+	env := map[string]string{
+		"GH_AW_HOME": GhAwHomeExprDefault,
+	}
 
-		// Set GH_AW_SAFE_OUTPUTS to path in /opt (read-only mount for agent container)
-		// The MCP server writes agent outputs to this file during execution
-		// This file is in /opt to prevent the agent container from having write access
-		env["GH_AW_SAFE_OUTPUTS"] = "/opt/gh-aw/safeoutputs/outputs.jsonl"
+	if data.SafeOutputs != nil {
+		// Set GH_AW_SAFE_OUTPUTS and related paths as job-level env vars.
+		// Using GhAwHomeExpr so paths adapt when GH_AW_HOME is overridden.
+		env["GH_AW_SAFE_OUTPUTS"] = GhAwHomeExpr + "/safeoutputs/outputs.jsonl"
+		env["GH_AW_SAFE_OUTPUTS_CONFIG_PATH"] = GhAwHomeExpr + "/safeoutputs/config.json"
+		env["GH_AW_SAFE_OUTPUTS_TOOLS_PATH"] = GhAwHomeExpr + "/safeoutputs/tools.json"
 
 		// Set GH_AW_MCP_LOG_DIR for safe outputs MCP server logging
 		// Store in mcp-logs directory so it's included in mcp-logs artifact
 		env["GH_AW_MCP_LOG_DIR"] = "/tmp/gh-aw/mcp-logs/safeoutputs"
 
-		// Set config and tools paths (readonly files in /opt/gh-aw)
-		env["GH_AW_SAFE_OUTPUTS_CONFIG_PATH"] = "/opt/gh-aw/safeoutputs/config.json"
-		env["GH_AW_SAFE_OUTPUTS_TOOLS_PATH"] = "/opt/gh-aw/safeoutputs/tools.json"
-
 		// Add asset-related environment variables
 		// These must always be set (even to empty) because awmg v0.0.12+ validates ${VAR} references
 		if data.SafeOutputs.UploadAssets != nil {
@@ -214,9 +213,6 @@ func (c *Compiler) buildMainJob(data *WorkflowData, activationJobCreated bool) (
 	// This contains the workflow ID with all hyphens removed and lowercased
 	// Used in cache keys to avoid spaces and special characters
 	if data.WorkflowID != "" {
-		if env == nil {
-			env = make(map[string]string)
-		}
 		sanitizedID := SanitizeWorkflowIDForCacheKey(data.WorkflowID)
 		env["GH_AW_WORKFLOW_ID_SANITIZED"] = sanitizedID
 	}

pkg/workflow/compiler_safe_outputs_job.go

@@ -268,7 +268,12 @@ func (c *Compiler) buildConsolidatedSafeOutputsJob(data *WorkflowData, mainJobNa
 			if len(c.generateCheckoutActionsFolder(data)) > 0 {
 				insertIndex += 6 // Checkout step (6 lines: name, uses, with, sparse-checkout header, actions, persist-credentials)
 			}
-			insertIndex += 4 // Setup step (4 lines: name, uses, with, destination)
+			enableCustomTokensForInsert := c.hasCustomTokenSafeOutputs(data.SafeOutputs)
+			if enableCustomTokensForInsert {
+				insertIndex += 4 // Setup step with custom tokens (4 lines: name, uses, with, safe-output-custom-tokens)
+			} else {
+				insertIndex += 2 // Setup step without custom tokens (2 lines: name, uses)
+			}
 		}
 
 		// Add artifact download steps count
@@ -385,6 +390,10 @@ func (c *Compiler) buildConsolidatedSafeOutputsJob(data *WorkflowData, mainJobNa
 func (c *Compiler) buildJobLevelSafeOutputEnvVars(data *WorkflowData, workflowID string) map[string]string {
 	envVars := make(map[string]string)
 
+	// Set GH_AW_HOME so steps can use $GH_AW_HOME without the :-fallback syntax.
+	// Use GhAwHomeExprDefault so callers can override via workflow/repo env.
+	envVars["GH_AW_HOME"] = GhAwHomeExprDefault
+
 	// Set GH_AW_WORKFLOW_ID to the workflow ID (filename without extension)
 	// This is used for branch naming in create_pull_request and other operations
 	envVars["GH_AW_WORKFLOW_ID"] = fmt.Sprintf("%q", workflowID)