fix: emit OTLP headers deprecation warning once via WorkflowData.OTLPHeaders

- extractOTLPConfigFromRaw now returns a deprecated bool flag instead
  of printing the warning inline (pure helper, no side-effects)
- injectOTLPConfig collects the deprecated flag from both extraction paths
  (raw frontmatter and ParsedFrontmatter fallback) and emits the warning
  exactly once
- Add WorkflowData.OTLPHeaders field; injectOTLPConfig sets it alongside
  OTLPEndpoint so downstream code has a single source of truth
- buildMCPGatewayConfig now reads workflowData.OTLPHeaders directly,
  eliminating the second call to extractOTLPConfigFromRaw and the
  duplicate deprecation warning it caused
- Update tests: extend TestExtractOTLPConfigFromRaw to assert the
  deprecated return value; add TestInjectOTLPConfig_OTLPHeadersField

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/9d7b90fb-97a7-4d37-81ea-71daf6c9e0e5

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Author: Copilot

pkg/workflow/compiler_types.go

@@ -491,6 +491,7 @@ type WorkflowData struct {
 	ParsedFrontmatter           *FrontmatterConfig              // cached parsed frontmatter configuration (for performance optimization)
 	RawFrontmatter              map[string]any                  // raw parsed frontmatter map (for passing to hash functions without re-parsing)
 	OTLPEndpoint                string                          // resolved OTLP endpoint (from observability.otlp.endpoint, including imports; set by injectOTLPConfig)
+	OTLPHeaders                 string                          // normalized OTLP headers in key=value,key=value format (from observability.otlp.headers, including imports; set by injectOTLPConfig)
 	ResolvedMCPServers          map[string]any                  // fully merged mcp-servers from main workflow and all imports (for mcp inspect)
 	ActionPinWarnings           map[string]bool                 // cache of already-warned action pin failures (key: "repo@version")
 	ActionMode                  ActionMode                      // action mode for workflow compilation (dev, release, script)

pkg/workflow/mcp_gateway_config.go

@@ -131,20 +131,9 @@ func buildMCPGatewayConfig(workflowData *WorkflowData) *MCPGatewayRuntimeConfig
 	// Use ${...} syntax for environment variable references that will be resolved by the gateway at runtime
 	// Per MCP Gateway Specification v1.0.0 section 4.2, variable expressions use "${VARIABLE_NAME}" syntax
 	//
-	// OTLPEndpoint and OTLPHeaders are derived from workflowData.OTLPEndpoint and the raw
-	// frontmatter headers string. These compile-time values (including GitHub Actions
-	// expressions such as ${{ secrets.X }}) are written directly into the gateway config JSON.
-	var otlpHeaders string
-	if workflowData.OTLPEndpoint != "" {
-		// Read headers from raw frontmatter (same source as injectOTLPConfig)
-		_, otlpHeaders = extractOTLPConfigFromRaw(workflowData.RawFrontmatter)
-		if otlpHeaders == "" && workflowData.ParsedFrontmatter != nil &&
-			workflowData.ParsedFrontmatter.Observability != nil &&
-			workflowData.ParsedFrontmatter.Observability.OTLP != nil {
-			normalized, _ := normalizeOTLPHeaders(workflowData.ParsedFrontmatter.Observability.OTLP.Headers)
-			otlpHeaders = normalized
-		}
-	}
+	// OTLPEndpoint and OTLPHeaders are read from workflowData fields set by injectOTLPConfig.
+	// These compile-time values (including GitHub Actions expressions such as ${{ secrets.X }})
+	// are written directly into the gateway config JSON.
 	return &MCPGatewayRuntimeConfig{
 		Port:                 int(DefaultMCPGatewayPort),                       // Will be formatted as "${MCP_GATEWAY_PORT}" in renderer
 		Domain:               "${MCP_GATEWAY_DOMAIN}",                          // Gateway variable expression
@@ -154,12 +143,11 @@ func buildMCPGatewayConfig(workflowData *WorkflowData) *MCPGatewayRuntimeConfig
 		PayloadSizeThreshold: payloadSizeThreshold,                             // Size threshold in bytes
 		TrustedBots:          workflowData.SandboxConfig.MCP.TrustedBots,       // Additional trusted bot identities from frontmatter
 		KeepaliveInterval:    workflowData.SandboxConfig.MCP.KeepaliveInterval, // Keepalive interval from frontmatter (0=default, -1=disabled, >0=custom)
-		// OTLPEndpoint and OTLPHeaders are set from workflowData.OTLPEndpoint which is the
-		// fully resolved OTLP endpoint (including imports) set by injectOTLPConfig. Using
-		// these fields ensures gateway OTLP config honours observability defined in imported
-		// shared workflows.
+		// OTLPEndpoint and OTLPHeaders are set from workflowData by injectOTLPConfig, which is
+		// the fully resolved OTLP config (including imports). Using these fields ensures gateway
+		// OTLP config honours observability defined in imported shared workflows.
 		OTLPEndpoint: workflowData.OTLPEndpoint,
-		OTLPHeaders:  otlpHeaders,
+		OTLPHeaders:  workflowData.OTLPHeaders,
 	}
 }
 

pkg/workflow/observability_otlp.go

@@ -145,7 +145,10 @@ func generateOTLPHeadersMaskStep() string {
 // succeeding -- that function may fail for workflows with complex tool configurations
 // (e.g. engine objects, array-style bash configs), which would leave ParsedFrontmatter
 // nil and prevent OTLP injection.
-func extractOTLPConfigFromRaw(frontmatter map[string]any) (endpoint, headers string) {
+//
+// The third return value is true when the deprecated string form was used for headers,
+// so the caller can emit a deprecation warning.
+func extractOTLPConfigFromRaw(frontmatter map[string]any) (endpoint, headers string, deprecated bool) {
 	obs, ok := frontmatter["observability"]
 	if !ok {
 		return
@@ -166,13 +169,7 @@ func extractOTLPConfigFromRaw(frontmatter map[string]any) (endpoint, headers str
 		endpoint = ep
 	}
 	if raw, ok := otlpMap["headers"]; ok {
-		normalized, deprecated := normalizeOTLPHeaders(raw)
-		if deprecated {
-			fmt.Fprintln(os.Stderr, console.FormatWarningMessage(
-				"observability.otlp.headers: string form is deprecated. Use the map form instead (e.g. headers: {Authorization: \"Bearer ${{ secrets.TOKEN }}\"})",
-			))
-		}
-		headers = normalized
+		headers, deprecated = normalizeOTLPHeaders(raw)
 	}
 	return
 }
@@ -191,7 +188,7 @@ func extractOTLPConfigFromRaw(frontmatter map[string]any) (endpoint, headers str
 func (c *Compiler) injectOTLPConfig(workflowData *WorkflowData) {
 	// Read OTLP config from the raw frontmatter map so that injection works even
 	// when ParseFrontmatterConfig failed (e.g. due to complex tool configs).
-	endpoint, headers := extractOTLPConfigFromRaw(workflowData.RawFrontmatter)
+	endpoint, headers, deprecated := extractOTLPConfigFromRaw(workflowData.RawFrontmatter)
 
 	// Fall back to ParsedFrontmatter when the raw map didn't yield an endpoint.
 	if endpoint == "" {
@@ -221,14 +218,20 @@ func (c *Compiler) injectOTLPConfig(workflowData *WorkflowData) {
 	if headers == "" && workflowData.ParsedFrontmatter != nil &&
 		workflowData.ParsedFrontmatter.Observability != nil &&
 		workflowData.ParsedFrontmatter.Observability.OTLP != nil {
-		normalized, deprecated := normalizeOTLPHeaders(workflowData.ParsedFrontmatter.Observability.OTLP.Headers)
-		if deprecated {
-			fmt.Fprintln(os.Stderr, console.FormatWarningMessage(
-				"observability.otlp.headers: string form is deprecated. Use the map form instead (e.g. headers: {Authorization: \"Bearer ${{ secrets.TOKEN }}\"})",
-			))
+		var parsedDeprecated bool
+		headers, parsedDeprecated = normalizeOTLPHeaders(workflowData.ParsedFrontmatter.Observability.OTLP.Headers)
+		if parsedDeprecated {
+			deprecated = true
 		}
-		headers = normalized
 	}
+
+	// Emit the deprecation warning once after resolving headers from all sources.
+	if deprecated {
+		fmt.Fprintln(os.Stderr, console.FormatWarningMessage(
+			"observability.otlp.headers: string form is deprecated. Use the map form instead (e.g. headers: {Authorization: \"Bearer ${{ secrets.TOKEN }}\"})",
+		))
+	}
+
 	if headers != "" {
 		otlpEnvLines += "\n  OTEL_EXPORTER_OTLP_HEADERS: " + headers
 		otlpLog.Printf("Injected OTEL_EXPORTER_OTLP_HEADERS env var")
@@ -241,8 +244,9 @@ func (c *Compiler) injectOTLPConfig(workflowData *WorkflowData) {
 	}
 	otlpLog.Printf("Injected OTEL env vars into workflow env block")
 
-	// Store the resolved endpoint so downstream code (mcp_gateway_config, mcp_setup_generator)
-	// can use workflowData.OTLPEndpoint as the single source of truth instead of
-	// re-reading raw frontmatter independently.
+	// Store the resolved endpoint and headers so downstream code (mcp_gateway_config,
+	// mcp_setup_generator) can use workflowData.OTLPEndpoint / OTLPHeaders as the single
+	// source of truth instead of re-reading raw frontmatter independently.
 	workflowData.OTLPEndpoint = endpoint
+	workflowData.OTLPHeaders = headers
 }

pkg/workflow/observability_otlp_test.go

@@ -406,10 +406,11 @@ func TestObservabilityConfigParsing(t *testing.T) {
 // TestExtractOTLPConfigFromRaw verifies direct raw-frontmatter OTLP extraction.
 func TestExtractOTLPConfigFromRaw(t *testing.T) {
 	tests := []struct {
-		name         string
-		frontmatter  map[string]any
-		wantEndpoint string
-		wantHeaders  string
+		name           string
+		frontmatter    map[string]any
+		wantEndpoint   string
+		wantHeaders    string
+		wantDeprecated bool
 	}{
 		{
 			name:        "nil frontmatter",
@@ -446,7 +447,7 @@ func TestExtractOTLPConfigFromRaw(t *testing.T) {
 			wantEndpoint: "${{ secrets.GH_AW_OTEL_ENDPOINT }}",
 		},
 		{
-			name: "observability.otlp with endpoint and headers",
+			name: "observability.otlp with endpoint and string headers (deprecated)",
 			frontmatter: map[string]any{
 				"observability": map[string]any{
 					"otlp": map[string]any{
@@ -455,11 +456,12 @@ func TestExtractOTLPConfigFromRaw(t *testing.T) {
 					},
 				},
 			},
-			wantEndpoint: "https://traces.example.com",
-			wantHeaders:  "${{ secrets.GH_AW_OTEL_HEADERS }}",
+			wantEndpoint:   "https://traces.example.com",
+			wantHeaders:    "${{ secrets.GH_AW_OTEL_HEADERS }}",
+			wantDeprecated: true,
 		},
 		{
-			name: "Sentry-style header with space in value",
+			name: "Sentry-style header with space in value (deprecated string form)",
 			frontmatter: map[string]any{
 				"observability": map[string]any{
 					"otlp": map[string]any{
@@ -468,16 +470,32 @@ func TestExtractOTLPConfigFromRaw(t *testing.T) {
 					},
 				},
 			},
-			wantEndpoint: "https://sentry.io/api/123/envelope/",
-			wantHeaders:  "x-sentry-auth=Sentry sentry_key=abc123",
+			wantEndpoint:   "https://sentry.io/api/123/envelope/",
+			wantHeaders:    "x-sentry-auth=Sentry sentry_key=abc123",
+			wantDeprecated: true,
+		},
+		{
+			name: "observability.otlp with endpoint and map headers (not deprecated)",
+			frontmatter: map[string]any{
+				"observability": map[string]any{
+					"otlp": map[string]any{
+						"endpoint": "https://traces.example.com",
+						"headers":  map[string]any{"Authorization": "Bearer tok"},
+					},
+				},
+			},
+			wantEndpoint:   "https://traces.example.com",
+			wantHeaders:    "Authorization=Bearer tok",
+			wantDeprecated: false,
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			gotEndpoint, gotHeaders := extractOTLPConfigFromRaw(tt.frontmatter)
+			gotEndpoint, gotHeaders, gotDeprecated := extractOTLPConfigFromRaw(tt.frontmatter)
 			assert.Equal(t, tt.wantEndpoint, gotEndpoint, "endpoint")
 			assert.Equal(t, tt.wantHeaders, gotHeaders, "headers")
+			assert.Equal(t, tt.wantDeprecated, gotDeprecated, "deprecated")
 		})
 	}
 }
@@ -668,6 +686,54 @@ func TestInjectOTLPConfig_OTLPEndpointField(t *testing.T) {
 	})
 }
 
+// TestInjectOTLPConfig_OTLPHeadersField verifies that injectOTLPConfig sets workflowData.OTLPHeaders
+// so that buildMCPGatewayConfig can read it directly instead of re-reading raw frontmatter.
+func TestInjectOTLPConfig_OTLPHeadersField(t *testing.T) {
+	c := &Compiler{}
+
+	t.Run("sets OTLPHeaders when headers are configured (map form)", func(t *testing.T) {
+		wd := &WorkflowData{
+			RawFrontmatter: map[string]any{
+				"observability": map[string]any{
+					"otlp": map[string]any{
+						"endpoint": "https://traces.example.com",
+						"headers":  map[string]any{"Authorization": "Bearer tok", "X-Tenant": "acme"},
+					},
+				},
+			},
+		}
+		c.injectOTLPConfig(wd)
+		assert.Equal(t, "Authorization=Bearer tok,X-Tenant=acme", wd.OTLPHeaders, "OTLPHeaders should be set from map form")
+	})
+
+	t.Run("sets OTLPHeaders when headers are configured (string form)", func(t *testing.T) {
+		wd := &WorkflowData{
+			RawFrontmatter: map[string]any{
+				"observability": map[string]any{
+					"otlp": map[string]any{
+						"endpoint": "https://traces.example.com",
+						"headers":  "Authorization=Bearer tok",
+					},
+				},
+			},
+		}
+		c.injectOTLPConfig(wd)
+		assert.Equal(t, "Authorization=Bearer tok", wd.OTLPHeaders, "OTLPHeaders should be set from string form")
+	})
+
+	t.Run("OTLPHeaders is empty when no headers are configured", func(t *testing.T) {
+		wd := &WorkflowData{
+			RawFrontmatter: map[string]any{
+				"observability": map[string]any{
+					"otlp": map[string]any{"endpoint": "https://traces.example.com"},
+				},
+			},
+		}
+		c.injectOTLPConfig(wd)
+		assert.Empty(t, wd.OTLPHeaders, "OTLPHeaders should be empty when no headers are configured")
+	})
+}
+
 // TestNormalizeOTLPHeaders verifies the normalizeOTLPHeaders helper function.
 func TestNormalizeOTLPHeaders(t *testing.T) {
 	tests := []struct {
@@ -869,14 +935,13 @@ func TestExtractOTLPConfigFromRaw_MapHeaders(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			gotEndpoint, gotHeaders := extractOTLPConfigFromRaw(tt.frontmatter)
+			gotEndpoint, gotHeaders, _ := extractOTLPConfigFromRaw(tt.frontmatter)
 			assert.Equal(t, tt.wantEndpoint, gotEndpoint, "endpoint")
 			assert.Equal(t, tt.wantHeaders, gotHeaders, "headers")
 		})
 	}
 }
 
-// TestObservabilityConfigParsing_MapHeaders verifies that the map form for headers is
 // correctly parsed by ParseFrontmatterConfig.
 func TestObservabilityConfigParsing_MapHeaders(t *testing.T) {
 	t.Run("map headers parsed as any type", func(t *testing.T) {