Allow cross-repo safe-outputs.dispatch-workflow allowlists

actions/setup/js/dispatch_workflow.cjs

@@ -55,7 +55,9 @@ async function main(config = {}) {
  // repo_helpers.cjs for consistent slug validation and glob-pattern matching (e.g. "org/*").
  if (isCrossRepoDispatch) {
  if (allowedRepos.size === 0) {
- throw new Error(`E004: Cross-repository dispatch to '${resolvedRepoSlug}' is not permitted. No allowlist is configured. Define 'allowed_repos' to enable cross-repository dispatch.`);
+ throw new Error(
+ `E004: Cross-repository dispatch to '${resolvedRepoSlug}' is not permitted. No allowlist is configured. Define 'allowed-repos' in the workflow's 'safe-outputs.dispatch-workflow' section to enable cross-repository dispatch.`
+ );
  }
  const repoValidation = validateTargetRepo(resolvedRepoSlug, contextRepoSlug, allowedRepos);
  if (!repoValidation.valid) {

docs/adr/39080-accept-allowed-repos-for-cross-repo-dispatch-workflow.md

@@ -0,0 +1,45 @@
+# ADR-39080: Accept `allowed-repos` for cross-repo `dispatch-workflow`
+
+**Date**: 2026-06-13
+**Status**: Draft
+
+## Context
+
+The `safe-outputs.dispatch-workflow` feature lets an agent dispatch other workflows, including in a different repository when `target-repo` is set. The JavaScript handler already enforced an allowlist at runtime (error `E004`), expecting an `allowed_repos` config value, but the workflow frontmatter schema and the Go compiler never accepted an `allowed-repos` key. As a result, an author who wrote a valid cross-repo configuration with `allowed-repos` failed at compile time, leaving no supported way to configure cross-repository dispatch end to end. Other cross-repo safe outputs (e.g. `create-code-scanning-alert`, `push-to-pull-request-branch`) already follow a consistent pattern of declaring an `allowed-repos` allowlist in frontmatter that is parsed by the compiler and emitted into the handler config.
+
+## Decision
+
+We will add `allowed-repos` to the `dispatch-workflow` safe-output as a first-class frontmatter field, wired through the full pipeline so cross-repo dispatch is configurable end to end:
+
+- Add `allowed-repos` to the `dispatch-workflow` JSON schema, accepting both an array of `owner/repo` slugs (supporting wildcards such as `org/*`) and a GitHub Actions expression resolving to a comma-separated list.
+- Parse `allowed-repos` into `DispatchWorkflowConfig.AllowedRepos` via the shared `ParseStringArrayFromConfig` helper.
+- Emit it into the runtime handler config as `allowed_repos` using `AddTemplatableStringSlice`, matching the JS handler contract and preserving templated allowlists the same way other cross-repo safe outputs do.
+
+We chose to mirror the existing cross-repo safe-output convention rather than invent a new mechanism, so configuration and templating behave identically across all safe outputs. The runtime error message is also tightened to point authors at the `safe-outputs.dispatch-workflow` section instead of an internal config key name.
+
+## Alternatives Considered
+
+### Alternative 1: Keep runtime-only enforcement, document the limitation
+Leave the schema and compiler unchanged and require users to rely on the runtime check, documenting that cross-repo dispatch could not be statically configured. Rejected because it leaves a valid feature unreachable through supported configuration — any `allowed-repos` config fails to compile — and contradicts the runtime handler that already expects the allowlist.
+
+### Alternative 2: Introduce a new, dispatch-specific allowlist key/shape
+Add a bespoke field (e.g. `dispatch-allowlist`) with its own parsing and emission logic specific to `dispatch-workflow`. Rejected because it would diverge from the established `allowed-repos` convention used by other cross-repo safe outputs, duplicating templating logic and increasing cognitive load for authors who already know the existing pattern.
+
+## Consequences
+
+### Positive
+- Cross-repository `dispatch-workflow` can now be configured end to end (schema → compiler → handler) without compile-time failures.
+- Behavior is consistent with other cross-repo safe outputs, including templated/expression-based allowlists, reducing surprise for authors.
+- Regression tests cover schema acceptance, config parsing, and handler-config emission for the new field.
+
+### Negative
+- Adds another surface (schema + parsing + emission) that must stay in sync with the JS handler's `allowed_repos` contract; a future change to one side risks drift.
+- Broadens the configuration surface of a security-sensitive feature (cross-repo dispatch), so the allowlist semantics and wildcard matching must be reviewed carefully.
+
+### Neutral
+- The frontmatter key is `allowed-repos` while the emitted handler key is `allowed_repos`; the naming difference follows the existing convention but must be remembered when tracing config through the pipeline.
+- No change to default behavior: omitting `allowed-repos` still blocks cross-repo dispatch via the existing `E004` error.
+
+---
+
+*This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/27468597143) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*

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

@@ -1218,6 +1218,9 @@ safe-outputs:
 
 - **`workflows`** (required) - List of workflow names (without `.md` extension) that the agent is allowed to dispatch. For same-repo dispatch, each workflow must exist locally and support the `workflow_dispatch` trigger.
 - **`max`** (optional) - Maximum number of workflow dispatches allowed (default: 1, maximum: 50). This prevents excessive workflow triggering.
+- **`target-repo`** (optional) - Target repository in `owner/repo` format for cross-repository dispatch.
+- **`allowed-repos`** (optional) - Allowlist of cross-repository dispatch targets. Required when `target-repo` points to a different repository. Supports repository slugs and wildcards such as `org/*`, or a GitHub Actions expression string (e.g. `"${{ inputs['allowed-repos'] }}"`) for dynamic allowlists.
+- **`target-ref`** (optional) - Git ref to dispatch on. In `workflow_call` relay scenarios, the compiler injects this automatically so the dispatch uses the target repository's branch or tag instead of the caller's `GITHUB_REF`.
 
 #### Validation Rules
 

pkg/parser/schema_safe_outputs_target_test.go

@@ -269,6 +269,16 @@ func TestMainWorkflowSchema_SafeOutputsTargetProperties(t *testing.T) {
  },
  },
  },
+ {
+ name: "dispatch-workflow with target-repo and allowed-repos",
+ safeOutputs: map[string]any{
+ "dispatch-workflow": map[string]any{
+ "workflows": []any{"worker"},
+ "target-repo": "github/github",
+ "allowed-repos": []any{"github/docs"},
+ },
+ },
+ },
  {
  name: "push-to-pull-request-branch with target and target-repo",
  safeOutputs: map[string]any{

pkg/parser/schemas/main_workflow_schema.json

@@ -9059,6 +9059,22 @@
  "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."
  },
+ "allowed-repos": {
+ "description": "List of repositories in format 'owner/repo' that cross-repository workflow dispatch may target. Supports arrays and GitHub Actions expressions resolving to a comma-separated list (e.g. '${{ inputs['allowed-repos'] }}').",
+ "oneOf": [
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ {
+ "type": "string",
+ "pattern": "^\\$\\{\\{.*\\}\\}$",
+ "description": "GitHub Actions expression resolving to a comma-separated list of repository slugs (e.g. '${{ inputs['allowed-repos'] }}')"
+ }
+ ]
+ },
  "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."

pkg/workflow/dispatch_workflow.go

@@ -13,6 +13,7 @@ type DispatchWorkflowConfig struct {
 	WorkflowFiles map[string]string `yaml:"workflow_files,omitempty"` // Map of workflow name to file extension (.lock.yml or .yml) - populated at compile time
 	AwContextWorkflows []string `yaml:"aw_context_workflows,omitempty"` // Workflows that declare aw_context in workflow_dispatch.inputs - populated at compile time
 	TargetRepoSlug string `yaml:"target-repo,omitempty"` // Target repository for cross-repo dispatch (owner/repo or GitHub Actions expression)
+	AllowedRepos []string `yaml:"allowed-repos,omitempty"` // Allowlist for cross-repository dispatch targets
 	TargetRef string `yaml:"target-ref,omitempty"` // Target ref for cross-repo dispatch; overrides the caller's GITHUB_REF
 }
 
@@ -60,6 +61,7 @@ func (c *Compiler) parseDispatchWorkflowConfig(outputMap map[string]any) *Dispat
 
  // Parse target-repo (optional cross-repo dispatch target)
  dispatchWorkflowConfig.TargetRepoSlug = extractStringFromMap(configMap, "target-repo", dispatchWorkflowLog)
+ dispatchWorkflowConfig.AllowedRepos = ParseStringArrayOrExprFromConfig(configMap, "allowed-repos", dispatchWorkflowLog)
 
  // Cap max at 50 (absolute maximum allowed) – only for literal integer values
  if maxVal := templatableIntValue(dispatchWorkflowConfig.Max); maxVal > 50 {

pkg/workflow/safe_outputs_cross_repo_config_test.go

@@ -11,6 +11,84 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// TestDispatchWorkflowConfigTargetRepo verifies that dispatch-workflow correctly parses
+// target-repo and allowed-repos fields.
+func TestDispatchWorkflowConfigTargetRepo(t *testing.T) {
+	compiler := NewCompiler()
+
+	tests := []struct {
+ name string
+ configMap map[string]any
+ expectedRepo string
+ expectedRepos []string
+ expectedToken string
+	}{
+ {
+ name: "target-repo and allowed-repos configured",
+ configMap: map[string]any{
+ "dispatch-workflow": map[string]any{
+ "workflows": []any{"worker"},
+ "target-repo": "githubnext/gh-aw-side-repo",
+ "allowed-repos": []any{"githubnext/gh-aw-side-repo"},
+ "github-token": "${{ secrets.TEMP_USER_PAT }}",
+ },
+ },
+ expectedRepo: "githubnext/gh-aw-side-repo",
+ expectedRepos: []string{"githubnext/gh-aw-side-repo"},
+ expectedToken: "${{ secrets.TEMP_USER_PAT }}",
+ },
+ {
+ name: "multiple allowed repos",
+ configMap: map[string]any{
+ "dispatch-workflow": map[string]any{
+ "workflows": []any{"worker"},
+ "target-repo": "org/primary-repo",
+ "allowed-repos": []any{"org/primary-repo", "org/secondary-repo"},
+ },
+ },
+ expectedRepo: "org/primary-repo",
+ expectedRepos: []string{"org/primary-repo", "org/secondary-repo"},
+ expectedToken: "",
+ },
+ {
+ name: "allowed-repos as GitHub Actions expression",
+ configMap: map[string]any{
+ "dispatch-workflow": map[string]any{
+ "workflows": []any{"worker"},
+ "target-repo": "${{ inputs.target_repo }}",
+ "allowed-repos": "${{ inputs['allowed-repos'] }}",
+ },
+ },
+ expectedRepo: "${{ inputs.target_repo }}",
+ expectedRepos: []string{"${{ inputs['allowed-repos'] }}"},
+ expectedToken: "",
+ },
+ {
+ name: "no cross-repo config",
+ configMap: map[string]any{
+ "dispatch-workflow": map[string]any{
+ "workflows": []any{"worker"},
+ "max": 2,
+ },
+ },
+ expectedRepo: "",
+ expectedRepos: nil,
+ expectedToken: "",
+ },
+	}
+
+	for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ cfg := compiler.parseDispatchWorkflowConfig(tt.configMap)
+
+ require.NotNil(t, cfg, "config should not be nil")
+ assert.Equal(t, tt.expectedRepo, cfg.TargetRepoSlug, "TargetRepoSlug mismatch")
+ assert.Equal(t, tt.expectedRepos, cfg.AllowedRepos, "AllowedRepos mismatch")
+ assert.Equal(t, tt.expectedToken, cfg.GitHubToken, "GitHubToken mismatch")
+ })
+	}
+}
+
 // TestCreateCodeScanningAlertConfigTargetRepo verifies that create-code-scanning-alert
 // correctly parses target-repo and allowed-repos fields.
 func TestCreateCodeScanningAlertConfigTargetRepo(t *testing.T) {
@@ -420,6 +498,42 @@ func TestPushToPullRequestBranchCrossRepoInHandlerConfig(t *testing.T) {
 	assert.Contains(t, allowedRepos, "githubnext/gh-aw-side-repo", "allowed_repos should contain the repo")
 }
 
+// TestDispatchWorkflowCrossRepoInHandlerConfig verifies that target-repo, allowed-repos,
+// and github-token are included in the handler manager config JSON for dispatch-workflow.
+func TestDispatchWorkflowCrossRepoInHandlerConfig(t *testing.T) {
+	compiler := NewCompiler()
+
+	workflowData := &WorkflowData{
+ Name: "Test",
+ SafeOutputs: &SafeOutputsConfig{
+ DispatchWorkflow: &DispatchWorkflowConfig{
+ BaseSafeOutputConfig: BaseSafeOutputConfig{
+ GitHubToken: "${{ secrets.TEMP_USER_PAT }}",
+ },
+ Workflows: []string{"worker"},
+ TargetRepoSlug: "githubnext/gh-aw-side-repo",
+ AllowedRepos: []string{"githubnext/gh-aw-side-repo"},
+ },
+ },
+	}
+
+	var steps []string
+	compiler.addHandlerManagerConfigEnvVar(&steps, workflowData)
+
+	require.NotEmpty(t, steps)
+	handlerConfig := extractHandlerConfig(t, strings.Join(steps, ""))
+
+	dispatchWorkflow, ok := handlerConfig["dispatch_workflow"]
+	require.True(t, ok, "dispatch_workflow config should be present")
+
+	assert.Equal(t, "${{ secrets.TEMP_USER_PAT }}", dispatchWorkflow["github-token"], "github-token should be in handler config")
+	assert.Equal(t, "githubnext/gh-aw-side-repo", dispatchWorkflow["target-repo"], "target-repo should be in handler config")
+
+	allowedRepos, ok := dispatchWorkflow["allowed_repos"]
+	require.True(t, ok, "allowed_repos should be present")
+	assert.Contains(t, allowedRepos, "githubnext/gh-aw-side-repo", "allowed_repos should contain the repo")
+}
+
 // TestHandlerManagerStepPerOutputTokenInHandlerConfig verifies that per-output tokens
 // (e.g., add-comment.github-token) are wired into the handler config JSON (GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG)
 // but NOT used as the step-level with.github-token. The step-level token follows the same

pkg/workflow/safe_outputs_handler_registry.go

@@ -598,7 +598,8 @@ var handlerRegistry = map[string]handlerBuilder{
  builder := newHandlerConfigBuilder().
  AddTemplatableInt("max", c.Max).
  AddStringSlice("workflows", c.Workflows).
- AddIfNotEmpty("target-repo", c.TargetRepoSlug)
+ AddIfNotEmpty("target-repo", c.TargetRepoSlug).
+ AddTemplatableStringSlice("allowed_repos", c.AllowedRepos)
 
  // Add workflow_files map if it has entries
  if len(c.WorkflowFiles) > 0 {