fix: cross-repo dispatch-workflow uses caller's GITHUB_REF instead of target repo's ref (#20790)

Author: Copilot

actions/setup/js/dispatch_workflow.cjs

@@ -82,8 +82,15 @@ async function main(config = {}) {
   // When running in a PR context, GITHUB_REF points to the merge ref (refs/pull/{PR_NUMBER}/merge)
   // which is not a valid branch ref for dispatching workflows. Instead, we need to use
   // GITHUB_HEAD_REF which contains the actual PR branch name.
+  // For cross-repo dispatch (workflow_call relay), the caller's GITHUB_REF has no meaning on
+  // the target repository, so we use the compiler-injected target-ref instead.
   let ref;
-  if (process.env.GITHUB_HEAD_REF) {
+  if (config["target-ref"]) {
+    // Compiler-injected target ref for cross-repo dispatch (workflow_call relay pattern).
+    // Takes precedence over all environment variables to avoid using the caller's ref.
+    ref = config["target-ref"];
+    core.info(`Using configured target-ref: ${ref}`);
+  } else if (process.env.GITHUB_HEAD_REF) {
     // We're in a pull_request event, use the PR branch ref
     ref = `refs/heads/${process.env.GITHUB_HEAD_REF}`;
     core.info(`Using PR branch ref: ${ref}`);

actions/setup/js/dispatch_workflow.test.cjs

@@ -659,4 +659,75 @@ describe("dispatch_workflow handler factory", () => {
       })
     );
   });
+
+  it("should use configured target-ref when dispatching cross-repo", async () => {
+    // Caller is on refs/heads/main, target workflow should run on feature-branch
+    process.env.GITHUB_REF = "refs/heads/main";
+    delete process.env.GITHUB_HEAD_REF;
+
+    const config = {
+      "target-repo": "other-org/other-repo",
+      "target-ref": "refs/heads/feature-branch",
+      workflows: ["target-workflow"],
+      workflow_files: { "target-workflow": ".lock.yml" },
+    };
+    const handler = await main(config);
+
+    await handler({ type: "dispatch_workflow", workflow_name: "target-workflow", inputs: {} }, {});
+
+    // Should dispatch to the configured target ref, NOT the caller's main
+    expect(github.rest.actions.createWorkflowDispatch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        owner: "other-org",
+        repo: "other-repo",
+        ref: "refs/heads/feature-branch",
+      })
+    );
+  });
+
+  it("should use caller GITHUB_REF when dispatching to same repo without target-ref", async () => {
+    process.env.GITHUB_REF = "refs/heads/feature-branch";
+    delete process.env.GITHUB_HEAD_REF;
+
+    const config = {
+      workflows: ["local-workflow"],
+      workflow_files: { "local-workflow": ".lock.yml" },
+    };
+    const handler = await main(config);
+
+    await handler({ type: "dispatch_workflow", workflow_name: "local-workflow", inputs: {} }, {});
+
+    // Same-repo dispatch should still use the caller's GITHUB_REF
+    expect(github.rest.actions.createWorkflowDispatch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        owner: "test-owner",
+        repo: "test-repo",
+        ref: "refs/heads/feature-branch",
+      })
+    );
+  });
+
+  it("should prefer configured target-ref over GITHUB_HEAD_REF for cross-repo dispatch", async () => {
+    process.env.GITHUB_REF = "refs/pull/42/merge";
+    process.env.GITHUB_HEAD_REF = "pr-branch";
+
+    const config = {
+      "target-repo": "other-org/other-repo",
+      "target-ref": "refs/heads/feature-branch",
+      workflows: ["target-workflow"],
+      workflow_files: { "target-workflow": ".lock.yml" },
+    };
+    const handler = await main(config);
+
+    await handler({ type: "dispatch_workflow", workflow_name: "target-workflow", inputs: {} }, {});
+
+    // Cross-repo should use configured target-ref, not the PR branch
+    expect(github.rest.actions.createWorkflowDispatch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        owner: "other-org",
+        repo: "other-repo",
+        ref: "refs/heads/feature-branch",
+      })
+    );
+  });
 });

docs/src/content/docs/reference/safe-outputs-specification.md

@@ -3074,13 +3074,15 @@ safe-outputs:
 - `max`: Operation limit (default: 3)
 - `workflows`: Allowlist of workflow names that may be dispatched
 - `target-repo`: Cross-repository target (owner/repo)
+- `target-ref`: Git ref (branch, tag, or SHA) to use when dispatching the workflow. In `workflow_call` relay scenarios this is auto-injected by the compiler from `needs.activation.outputs.target_ref`, ensuring the correct platform branch is used instead of the caller's `GITHUB_REF`.
 - `allowed-repos`: Cross-repo allowlist (supports wildcards, e.g. `org/*`)
 
 **Notes**:
 - Requires ONLY `actions: write` permission (no `contents: read` needed)
 - Target workflow must support `workflow_dispatch` trigger
 - Workflow inputs are validated against target workflow's input schema
 - Cross-repository dispatch requires appropriate `actions: write` permissions in the target repository
+- In `workflow_call` relay (CentralRepoOps) scenarios, the compiler automatically injects both `target-repo` and `target-ref` from `needs.activation.outputs.*` so the dispatch targets the correct platform repository and branch
 
 ---
 

pkg/parser/schemas/main_workflow_schema.json

@@ -5341,7 +5341,7 @@
                   "items": {
                     "type": "string"
                   },
-                  "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern — files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
+                  "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern \u2014 files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
                 }
               },
               "additionalProperties": false,
@@ -6393,7 +6393,7 @@
                   "items": {
                     "type": "string"
                   },
-                  "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern — files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
+                  "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern \u2014 files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
                 }
               },
               "additionalProperties": false
@@ -6541,6 +6541,14 @@
                 "github-token": {
                   "$ref": "#/$defs/github_token",
                   "description": "GitHub token to use for dispatching workflows. Overrides global github-token if specified."
+                },
+                "target-repo": {
+                  "type": "string",
+                  "description": "Target repository in format 'owner/repo' for cross-repository workflow dispatch. When specified, the workflow will be dispatched to the target repository instead of the current one."
+                },
+                "target-ref": {
+                  "type": "string",
+                  "description": "Git ref (branch, tag, or SHA) to use when dispatching the workflow. For workflow_call relay scenarios this is auto-injected by the compiler from needs.activation.outputs.target_ref. Overrides the caller's GITHUB_REF."
                 }
               },
               "required": ["workflows"],
@@ -7659,7 +7667,13 @@
     },
     "dependencies": {
       "description": "APM package references to install. Supports array format (list of package slugs) or object format with packages and isolated fields.",
-      "examples": [["microsoft/apm-sample-package", "acme/custom-tools"], { "packages": ["microsoft/apm-sample-package"], "isolated": true }],
+      "examples": [
+        ["microsoft/apm-sample-package", "acme/custom-tools"],
+        {
+          "packages": ["microsoft/apm-sample-package"],
+          "isolated": true
+        }
+      ],
       "oneOf": [
         {
           "type": "array",
@@ -8219,12 +8233,16 @@
                     "query": {
                       "type": "object",
                       "description": "Static query parameters",
-                      "additionalProperties": { "type": "string" }
+                      "additionalProperties": {
+                        "type": "string"
+                      }
                     },
                     "body-inject": {
                       "type": "object",
                       "description": "Key/value pairs injected into the JSON request body",
-                      "additionalProperties": { "type": "string" }
+                      "additionalProperties": {
+                        "type": "string"
+                      }
                     }
                   },
                   "additionalProperties": false
@@ -8242,15 +8260,17 @@
                 },
                 "supported": {
                   "type": "array",
-                  "items": { "type": "string" },
+                  "items": {
+                    "type": "string"
+                  },
                   "description": "List of supported model identifiers"
                 }
               },
               "additionalProperties": false
             },
             "auth": {
               "type": "array",
-              "description": "Authentication bindings — maps logical roles (e.g. 'api-key') to GitHub Actions secret names",
+              "description": "Authentication bindings \u2014 maps logical roles (e.g. 'api-key') to GitHub Actions secret names",
               "items": {
                 "type": "object",
                 "properties": {

pkg/workflow/compiler_safe_outputs_config.go

@@ -577,6 +577,7 @@ var handlerRegistry = map[string]handlerBuilder{
 			builder.AddDefault("workflow_files", c.WorkflowFiles)
 		}
 
+		builder.AddIfNotEmpty("target-ref", c.TargetRef)
 		builder.AddIfNotEmpty("github-token", c.GitHubToken)
 		return builder.Build()
 	},
@@ -731,12 +732,18 @@ func (c *Compiler) addHandlerManagerConfigEnvVar(steps *[]string, data *Workflow
 	fullManifestFiles := getAllManifestFiles(extraManifestFiles...)
 	fullPathPrefixes := getProtectedPathPrefixes(extraPathPrefixes...)
 
-	// For workflow_call relay workflows, inject the resolved platform repo into the
+	// For workflow_call relay workflows, inject the resolved platform repo and ref into the
 	// dispatch_workflow handler config so dispatch targets the host repo, not the caller's.
 	safeOutputs := data.SafeOutputs
-	if hasWorkflowCallTrigger(data.On) && safeOutputs.DispatchWorkflow != nil && safeOutputs.DispatchWorkflow.TargetRepoSlug == "" {
-		safeOutputs = safeOutputsWithDispatchTargetRepo(safeOutputs, "${{ needs.activation.outputs.target_repo }}")
-		compilerSafeOutputsConfigLog.Print("Injecting target_repo into dispatch_workflow config for workflow_call relay")
+	if hasWorkflowCallTrigger(data.On) && safeOutputs.DispatchWorkflow != nil {
+		if safeOutputs.DispatchWorkflow.TargetRepoSlug == "" {
+			safeOutputs = safeOutputsWithDispatchTargetRepo(safeOutputs, "${{ needs.activation.outputs.target_repo }}")
+			compilerSafeOutputsConfigLog.Print("Injecting target_repo into dispatch_workflow config for workflow_call relay")
+		}
+		if safeOutputs.DispatchWorkflow.TargetRef == "" {
+			safeOutputs = safeOutputsWithDispatchTargetRef(safeOutputs, "${{ needs.activation.outputs.target_ref }}")
+			compilerSafeOutputsConfigLog.Print("Injecting target_ref into dispatch_workflow config for workflow_call relay")
+		}
 	}
 
 	// Build configuration for each handler using the registry
@@ -784,6 +791,17 @@ func safeOutputsWithDispatchTargetRepo(cfg *SafeOutputsConfig, targetRepo string
 	return &configCopy
 }
 
+// safeOutputsWithDispatchTargetRef returns a shallow copy of cfg with the dispatch_workflow
+// TargetRef overridden to targetRef. Only DispatchWorkflow is deep-copied; all other
+// pointer fields remain shared. This avoids mutating the original config.
+func safeOutputsWithDispatchTargetRef(cfg *SafeOutputsConfig, targetRef string) *SafeOutputsConfig {
+	dispatchCopy := *cfg.DispatchWorkflow
+	dispatchCopy.TargetRef = targetRef
+	configCopy := *cfg
+	configCopy.DispatchWorkflow = &dispatchCopy
+	return &configCopy
+}
+
 // getEngineAgentFileInfo returns the engine-specific manifest filenames and path prefixes
 // by type-asserting the active engine to AgentFileProvider.  Returns empty slices when
 // the engine is not set or does not implement the interface.

pkg/workflow/dispatch_workflow.go

@@ -12,6 +12,7 @@ type DispatchWorkflowConfig struct {
 	Workflows            []string          `yaml:"workflows,omitempty"`      // List of workflow names (without .md extension) to allow dispatching
 	WorkflowFiles        map[string]string `yaml:"workflow_files,omitempty"` // Map of workflow name to file extension (.lock.yml or .yml) - populated at compile time
 	TargetRepoSlug       string            `yaml:"target-repo,omitempty"`    // Target repository for cross-repo dispatch (owner/repo or GitHub Actions expression)
+	TargetRef            string            `yaml:"target-ref,omitempty"`     // Target ref for cross-repo dispatch; overrides the caller's GITHUB_REF
 }
 
 // parseDispatchWorkflowConfig handles dispatch-workflow configuration
@@ -51,6 +52,11 @@ func (c *Compiler) parseDispatchWorkflowConfig(outputMap map[string]any) *Dispat
 			// Parse common base fields with default max of 1
 			c.parseBaseSafeOutputConfig(configMap, &dispatchWorkflowConfig.BaseSafeOutputConfig, 1)
 
+			// Parse target-ref (optional ref for cross-repo dispatch)
+			if targetRef, ok := configMap["target-ref"].(string); ok && targetRef != "" {
+				dispatchWorkflowConfig.TargetRef = targetRef
+			}
+
 			// Cap max at 50 (absolute maximum allowed) – only for literal integer values
 			if maxVal := templatableIntValue(dispatchWorkflowConfig.Max); maxVal > 50 {
 				dispatchWorkflowLog.Printf("Max value %d exceeds limit, capping at 50", maxVal)