Add observability.otlp.ignore-if-missing to downgrade missing OTLP config to warnings (#32173)

Author: Copilot

actions/setup/js/assign_agent_helpers.cjs

@@ -126,7 +126,7 @@ async function findAgent(owner, repo, agentName, githubClient = github) {
     core.error(`Failed to find ${agentName} agent: ${errorMessage}`);
 
     // Re-throw authentication/permission errors so they can be handled by the caller
-    // This allows ignore-if-missing logic to work properly
+    // This allows if-missing: ignore logic to work properly
     if (
       errorMessage.includes("Bad credentials") ||
       errorMessage.includes("Not Authenticated") ||

actions/setup/js/start_mcp_gateway.cjs

@@ -64,6 +64,95 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * Normalizes GH_AW_OTLP_IF_MISSING to a supported mode.
+ * @param {string | undefined} value
+ * @returns {"error" | "warn" | "ignore"}
+ */
+function getOTLPIfMissingMode(value) {
+  const normalized = (value || "").trim().toLowerCase();
+  if (normalized === "warn" || normalized === "ignore") {
+    return normalized;
+  }
+  return "error";
+}
+
+/**
+ * Returns true when GH_AW_OTLP_IF_MISSING is set to "ignore".
+ * @param {string | undefined} value
+ * @returns {boolean}
+ */
+function isOTLPIfMissingIgnore(value) {
+  return getOTLPIfMissingMode(value) === "ignore";
+}
+
+/**
+ * Returns true when OTLP headers contain at least one non-empty value.
+ * NOTE: Unexpected primitive values are treated as non-empty so they are
+ * preserved for downstream validation/error handling.
+ * @param {unknown} headers
+ * @returns {boolean}
+ */
+function hasNonEmptyOTLPHeaders(headers) {
+  if (headers == null) {
+    return false;
+  }
+  if (typeof headers === "string") {
+    return headers.trim() !== "";
+  }
+  if (Array.isArray(headers)) {
+    return headers.some(item => hasNonEmptyOTLPHeaders(item));
+  }
+  if (typeof headers === "object") {
+    return Object.values(headers).some(value => hasNonEmptyOTLPHeaders(value));
+  }
+  // For unexpected primitive types, keep headers
+  // intact so downstream validation can fail explicitly rather than silently
+  // treating them as "missing".
+  return true;
+}
+
+/**
+ * Apply observability.otlp.if-missing: ignore behavior to gateway OTLP config.
+ * When enabled, missing endpoint values are downgraded to warnings and OTLP
+ * gateway configuration is skipped instead of hard-failing the workflow.
+ *
+ * @param {Record<string, unknown>} configObj
+ */
+function applyOTLPIgnoreIfMissing(configObj) {
+  const mode = getOTLPIfMissingMode(process.env.GH_AW_OTLP_IF_MISSING);
+  const shouldDowngradeMissing = mode === "warn" || mode === "ignore";
+  const shouldWarn = mode === "warn";
+  if (!shouldDowngradeMissing) {
+    return;
+  }
+  const gw = configObj.gateway;
+  if (!gw || typeof gw !== "object" || Array.isArray(gw)) {
+    return;
+  }
+  const gateway = /** @type {Record<string, unknown>} */ gw;
+  const otel = gateway["opentelemetry"];
+  if (!otel || typeof otel !== "object" || Array.isArray(otel)) {
+    return;
+  }
+  const otelConfig = /** @type {Record<string, unknown>} */ otel;
+  const endpoint = typeof otelConfig["endpoint"] === "string" ? otelConfig["endpoint"].trim() : "";
+  if (!endpoint) {
+    delete gateway["opentelemetry"];
+    if (shouldWarn) {
+      core.warning("OTLP endpoint is missing/empty and GH_AW_OTLP_IF_MISSING=warn; skipping MCP gateway OTLP configuration.");
+    }
+    return;
+  }
+  const headers = otelConfig["headers"];
+  if ("headers" in otelConfig && !hasNonEmptyOTLPHeaders(headers)) {
+    delete otelConfig["headers"];
+    if (shouldWarn) {
+      core.warning("OTLP headers are missing/empty and GH_AW_OTLP_IF_MISSING=warn; continuing without MCP gateway OTLP headers.");
+    }
+  }
+}
+
 /**
  * Check whether a process is alive.
  * @param {number} pid
@@ -258,6 +347,8 @@ async function main() {
     process.exit(1);
   }
 
+  applyOTLPIgnoreIfMissing(configObj);
+
   core.info("Configuration validated successfully");
   printTiming(configValidationStart, "Configuration validation");
   core.info("");
@@ -297,7 +388,7 @@ async function main() {
     core.error("ERROR: Gateway process stdin is not available");
     process.exit(1);
   }
-  child.stdin.write(mcpConfig);
+  child.stdin.write(JSON.stringify(configObj));
   child.stdin.end();
 
   // Allow the child to run independently
@@ -740,11 +831,18 @@ async function main() {
   }
 }
 
-main().catch(err => {
-  const message = err instanceof Error ? err.message : String(err);
-  const stack = err instanceof Error ? err.stack : undefined;
-  if (stack) core.error(stack);
-  core.setFailed(`FATAL: ${message}`);
-});
+if (require.main === module) {
+  main().catch(err => {
+    const message = err instanceof Error ? err.message : String(err);
+    const stack = err instanceof Error ? err.stack : undefined;
+    if (stack) core.error(stack);
+    core.setFailed(`FATAL: ${message}`);
+  });
+}
 
-module.exports = {};
+module.exports = {
+  applyOTLPIgnoreIfMissing,
+  getOTLPIfMissingMode,
+  hasNonEmptyOTLPHeaders,
+  isOTLPIfMissingIgnore,
+};

actions/setup/js/start_mcp_gateway.test.cjs

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { applyOTLPIgnoreIfMissing, getOTLPIfMissingMode, hasNonEmptyOTLPHeaders } from "./start_mcp_gateway.cjs";
+
+describe("start_mcp_gateway OTLP if-missing helpers", () => {
+  let originalWarning;
+
+  beforeEach(() => {
+    originalWarning = global.core.warning;
+    global.core.warning = vi.fn();
+  });
+
+  afterEach(() => {
+    delete process.env.GH_AW_OTLP_IF_MISSING;
+    global.core.warning = originalWarning;
+  });
+
+  it("normalizes if-missing mode", () => {
+    expect(getOTLPIfMissingMode(undefined)).toBe("error");
+    expect(getOTLPIfMissingMode(" warn ")).toBe("warn");
+    expect(getOTLPIfMissingMode("ignore")).toBe("ignore");
+    expect(getOTLPIfMissingMode("invalid")).toBe("error");
+  });
+
+  it("detects non-empty OTLP headers for string/map/array forms", () => {
+    expect(hasNonEmptyOTLPHeaders("")).toBe(false);
+    expect(hasNonEmptyOTLPHeaders("Authorization=Bearer token")).toBe(true);
+    expect(hasNonEmptyOTLPHeaders({ Authorization: "" })).toBe(false);
+    expect(hasNonEmptyOTLPHeaders({ Authorization: "Bearer token" })).toBe(true);
+    expect(hasNonEmptyOTLPHeaders(["", "  "])).toBe(false);
+    expect(hasNonEmptyOTLPHeaders(["", "token"])).toBe(true);
+  });
+
+  it("is a no-op when if-missing mode is unset/error", () => {
+    const config = {
+      gateway: {
+        opentelemetry: {
+          endpoint: "   ",
+          headers: "",
+        },
+      },
+    };
+    applyOTLPIgnoreIfMissing(config);
+    expect(config.gateway.opentelemetry).toEqual({
+      endpoint: "   ",
+      headers: "",
+    });
+  });
+
+  it("removes opentelemetry when endpoint is empty for warn mode and emits a warning", () => {
+    const warningSpy = vi.fn();
+    global.core.warning = warningSpy;
+    process.env.GH_AW_OTLP_IF_MISSING = "warn";
+
+    const config = {
+      gateway: {
+        opentelemetry: {
+          endpoint: "   ",
+          headers: { Authorization: "" },
+        },
+      },
+    };
+
+    applyOTLPIgnoreIfMissing(config);
+
+    expect(config.gateway.opentelemetry).toBeUndefined();
+    expect(warningSpy).toHaveBeenCalledOnce();
+    expect(warningSpy).toHaveBeenCalledWith(expect.stringContaining("OTLP endpoint is missing/empty"));
+  });
+
+  it("removes empty headers object for warn mode and emits a warning", () => {
+    const warningSpy = vi.fn();
+    global.core.warning = warningSpy;
+    process.env.GH_AW_OTLP_IF_MISSING = "warn";
+
+    const config = {
+      gateway: {
+        opentelemetry: {
+          endpoint: "https://collector.example/v1/traces",
+          headers: { Authorization: "", "X-Tenant": "   " },
+        },
+      },
+    };
+
+    applyOTLPIgnoreIfMissing(config);
+
+    expect(config.gateway.opentelemetry.headers).toBeUndefined();
+    expect(warningSpy).toHaveBeenCalledOnce();
+    expect(warningSpy).toHaveBeenCalledWith(expect.stringContaining("OTLP headers are missing/empty"));
+  });
+
+  it("removes empty headers object for ignore mode without warning", () => {
+    const warningSpy = vi.fn();
+    global.core.warning = warningSpy;
+    process.env.GH_AW_OTLP_IF_MISSING = "ignore";
+
+    const config = {
+      gateway: {
+        opentelemetry: {
+          endpoint: "https://collector.example/v1/traces",
+          headers: { Authorization: "" },
+        },
+      },
+    };
+
+    applyOTLPIgnoreIfMissing(config);
+
+    expect(config.gateway.opentelemetry.headers).toBeUndefined();
+    expect(warningSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -895,6 +895,7 @@ observability:
 |-------|------|-------------|
 | `observability.otlp.endpoint` | string, object, or array | OTLP/HTTP collector endpoint URL. Accepts a plain URL string, a single `{url, headers}` object, or an array of `{url, headers}` objects for concurrent fan-out to multiple collectors. When a static URL is provided, its hostname is automatically added to the network firewall allowlist. |
 | `observability.otlp.headers` | map or string | HTTP headers sent with every OTLP export request. Only applies when `endpoint` is a plain string; object and array endpoint entries carry their own per-endpoint headers. |
+| `observability.otlp.if-missing` | string (`error`, `warn`, `ignore`) | Controls behavior when OTLP endpoint/header values resolve to empty values at runtime (for example because a referenced secret is unset): `error` (default) fails startup, `warn` logs a warning and skips MCP gateway OTLP configuration, `ignore` skips MCP gateway OTLP configuration without warning. This setting affects MCP gateway setup only. |
 
 ### `observability.otlp.endpoint`
 
@@ -972,6 +973,7 @@ When `observability.otlp` is configured, the following environment variables are
 | `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` headers for the first endpoint. Set only when headers are configured. |
 | `OTEL_SERVICE_NAME` | Always `gh-aw`. |
 | `GH_AW_OTLP_ENDPOINTS` | JSON-encoded array of all endpoint entries (`[{"url":"...","headers":"..."}]`). Used by JavaScript action scripts to fan out spans to multiple endpoints. |
+| `GH_AW_OTLP_IF_MISSING` | Set to `warn` or `ignore` when `observability.otlp.if-missing` is configured. Used by runtime gateway setup to downgrade missing OTLP endpoint/header values from startup errors to non-fatal behavior for MCP gateway setup only. |
 | `COPILOT_OTEL_FILE_EXPORTER_PATH` | Path where Copilot CLI writes its own OTLP spans (`/tmp/gh-aw/copilot-otel.jsonl`). Copilot CLI detects this variable and writes its traces here; gh-aw forwards these traces to configured endpoints at the end of each run. |
 
 > [!NOTE]

pkg/parser/schemas/main_workflow_schema.json

@@ -9317,6 +9317,12 @@
                   "description": "Deprecated: use the map form instead. Comma-separated list of key=value HTTP headers to include with every OTLP export request (e.g. 'Authorization=Bearer <token>'). Supports GitHub Actions expressions such as ${{ secrets.OTLP_HEADERS }}. Injected as the OTEL_EXPORTER_OTLP_HEADERS environment variable."
                 }
               ]
+            },
+            "if-missing": {
+              "type": "string",
+              "enum": ["error", "warn", "ignore"],
+              "default": "error",
+              "description": "How to handle missing OTLP endpoint/header values at runtime (for example from unset secrets). 'error' fails workflow startup (default), 'warn' logs a warning and skips MCP gateway OTLP configuration, and 'ignore' skips MCP gateway OTLP configuration without warning. This affects MCP gateway setup only; workflow-level OTEL_* environment variables are still injected."
             }
           },
           "additionalProperties": false

pkg/workflow/frontmatter_types.go

@@ -225,6 +225,15 @@ type OTLPConfig struct {
 	//   - a comma-separated list of key=value pairs (e.g. "Authorization=Bearer <token>")
 	// Both forms are injected as the standard OTEL_EXPORTER_OTLP_HEADERS environment variable.
 	Headers any `json:"headers,omitempty"`
+
+	// IfMissing controls runtime behavior when OTLP endpoint/header values are
+	// missing (for example because a referenced secret is unset). Supported values:
+	//   - "error" (default): fail workflow startup
+	//   - "warn": log a warning and skip MCP gateway OTLP config
+	//   - "ignore": skip MCP gateway OTLP config without warning
+	// This setting affects MCP gateway setup only. Other OTLP-aware steps still
+	// receive workflow-level OTEL_* environment variables.
+	IfMissing string `json:"if-missing,omitempty"`
 }
 
 // ObservabilityConfig represents workflow observability options.

pkg/workflow/observability_otlp.go

@@ -99,6 +99,57 @@ func getOTLPEndpointEnvValue(config *FrontmatterConfig) string {
 	return ""
 }
 
+// normalizeOTLPIfMissingMode returns a validated if-missing mode.
+// Empty string means "unset/default (error)".
+func normalizeOTLPIfMissingMode(mode string) string {
+	switch strings.ToLower(strings.TrimSpace(mode)) {
+	case "":
+		return ""
+	case "error", "warn", "ignore":
+		return strings.ToLower(strings.TrimSpace(mode))
+	default:
+		return ""
+	}
+}
+
+// getOTLPIfMissingMode returns observability.otlp.if-missing mode.
+// Returns empty string when unset or invalid.
+func getOTLPIfMissingMode(config *FrontmatterConfig, frontmatter map[string]any) string {
+	if config != nil && config.Observability != nil && config.Observability.OTLP != nil {
+		if mode := normalizeOTLPIfMissingMode(config.Observability.OTLP.IfMissing); mode != "" {
+			return mode
+		}
+	}
+	if frontmatter == nil {
+		return ""
+	}
+	obsAny, ok := frontmatter["observability"]
+	if !ok {
+		return ""
+	}
+	obsMap, ok := obsAny.(map[string]any)
+	if !ok {
+		return ""
+	}
+	otlpAny, ok := obsMap["otlp"]
+	if !ok {
+		return ""
+	}
+	otlpMap, ok := otlpAny.(map[string]any)
+	if !ok {
+		return ""
+	}
+	if v, ok := otlpMap["if-missing"].(string); ok {
+		if mode := normalizeOTLPIfMissingMode(v); mode != "" {
+			return mode
+		}
+		if strings.TrimSpace(v) != "" {
+			otlpLog.Printf("Ignoring invalid observability.otlp.if-missing value %q (expected one of: error, warn, ignore)", v)
+		}
+	}
+	return ""
+}
+
 // isOTLPHeadersPresent returns true when OTEL_EXPORTER_OTLP_HEADERS or
 // GH_AW_OTLP_ALL_HEADERS has been injected into the workflow-level env block.
 // This indicates that header masking is needed so that authentication tokens in
@@ -349,6 +400,7 @@ func (c *Compiler) injectOTLPConfig(workflowData *WorkflowData) {
 
 	firstEndpoint := entries[0].URL
 	firstHeaders := entries[0].Headers
+	ifMissingMode := getOTLPIfMissingMode(workflowData.ParsedFrontmatter, workflowData.RawFrontmatter)
 
 	// 2. Inject OTEL env vars into the workflow-level env: block.
 	//    OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME are set to the first
@@ -376,6 +428,10 @@ func (c *Compiler) injectOTLPConfig(workflowData *WorkflowData) {
 		otlpEnvLines += "\n  GH_AW_OTLP_ENDPOINTS: '" + escapedEncoded + "'"
 		otlpLog.Printf("Injected GH_AW_OTLP_ENDPOINTS env var")
 	}
+	if ifMissingMode == "warn" || ifMissingMode == "ignore" {
+		otlpEnvLines += "\n  GH_AW_OTLP_IF_MISSING: " + ifMissingMode
+		otlpLog.Printf("Injected GH_AW_OTLP_IF_MISSING env var (%s)", ifMissingMode)
+	}
 
 	if workflowData.Env == "" {
 		workflowData.Env = "env:\n" + otlpEnvLines