[bug] base-branch in assign-to-agent uses customInstructions text instead of GraphQL baseRef field

[steliosfran]

Bug: base-branch does not work because baseRef is not passed in the GraphQL mutation

Context

Issue #17046 requested base-branch support for assign-to-agent. PR #17133 implemented it and was merged. However, the feature does not work — Copilot still opens PRs against main even when base-branch: "develop" is configured.

Root Cause

The GitHub GraphQL API's AgentAssignmentInput has a dedicated baseRef field:

baseRef (String) — The base ref/branch for the repository. Defaults to the default branch if not provided.

— GitHub GraphQL API docs: AgentAssignmentInput

The official documentation shows it being used directly:

agentAssignment: {
  targetRepositoryId: "REPOSITORY_ID",
  baseRef: "main",
  customInstructions: "Fix the reported bug"
}

The REST API equivalent is base_branch in agent_assignment:

{
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": ""
  }
}

PR #17133 does not use this field. Instead, it injects a natural language instruction into customInstructions:

IMPORTANT: Create your branch from the 'develop' branch, NOT from 'main'.

This text is prepended to customInstructions and passed as a string to the mutation. The baseRef field in agentAssignment is never set.

Why This Fails

1. Copilot does not reliably follow natural language instructions about which branch to use. It has its own branch resolution logic and the customInstructions text is advisory, not authoritative.

2. The buildBranchInstruction() wording is ambiguous — it says "Create your branch from" but does not say "open the PR targeting." These are different git operations (branching from vs. PR target).

3. The GraphQL API has a formal baseRef parameter specifically for this purpose behind the GraphQL-Features: issues_copilot_assignment_api_support header. This is how the GitHub.com UI specifies the base branch when assigning Copilot.

Current Code (PR #17133)

In actions/setup/js/assign_agent_helpers.cjs, the agentAssignment only passes:

• targetRepositoryId
• model
• customAgent
• customInstructions

baseRef is never included in the mutation variables.

Fix

Add baseRef to the agentAssignment fields in assignAgentToIssue(), following the same pattern as other fields:

if (baseBranch) {
  agentAssignmentFields.push("baseRef: $baseRef");
  agentAssignmentParams.push("$baseRef: String!");
  variables.baseRef = baseBranch;
}

Also add the required feature flag header if not already present:

GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection

The buildBranchInstruction() text injection into customInstructions should be removed (or kept as a secondary hint), since baseRef is the authoritative mechanism.

Implementation Plan

1. Update assignAgentToIssue() in actions/setup/js/assign_agent_helpers.cjs

Add baseRef as a parameter and include it in the GraphQL mutation agentAssignment:

if (baseBranch) {
  agentAssignmentFields.push("baseRef: $baseRef");
  agentAssignmentParams.push("$baseRef: String!");
  variables.baseRef = baseBranch;
}

2. Update assign_to_agent.cjs handler

Pass the resolved effectiveBaseBranch to assignAgentToIssue() as a new baseBranch parameter (instead of only using it to build a text instruction).

3. Remove or demote buildBranchInstruction()

Since baseRef is the formal API mechanism, the natural language instruction in customInstructions is redundant. Either:

• Remove buildBranchInstruction() entirely, or
• Keep it as a soft secondary hint but make baseRef the primary mechanism

4. Add the feature flag header

Ensure the GraphQL request includes:

GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection

5. Update tests

• Update assign_agent_helpers.test.cjs to verify baseRef appears in the mutation
• Test that baseRef is correctly passed when GH_AW_AGENT_BASE_BRANCH is set
• Test backward compatibility when no base branch is configured

6. Follow Guidelines

• Use error message format: "what's wrong. what's expected. example"
• Run make agent-finish before completing

Reproduction

safe-outputs:
  assign-to-agent:
    target: "*"
    pull-request-repo: "org/code-repo"   # default branch: develop
    base-branch: "develop"
    github-token: ${{ secrets.TOKEN }}

Result: Copilot branches from main and opens PR targeting main, ignoring the base-branch: "develop" configuration.

References

• Issue [enhancement] Add base-branch support to assign-to-agent safe output for cross-repo PR creation #17046 — Original enhancement request
• PR Add base-branch support to assign-to-agent for cross-repo PR creation #17133 — Current (broken) implementation
• AgentAssignmentInput docs — shows baseRef field
• Copilot coding agent API docs — shows baseRef usage examples