Target aspire.dev release branch by milestone in pr-docs-check workflow

[IEvangelist]

Description

Updates the pr-docs-check agentic workflow so draft PRs opened on microsoft/aspire.dev target the correct release branch instead of always defaulting to main.

Motivation

microsoft/aspire ships versioned releases, while microsoft/aspire.dev's main tracks the latest build bits. Today the workflow always opens docs PRs against aspire.dev main, which is usually wrong for changes associated with a shipped/servicing release.

What changed

The agent prompt now resolves a target branch on microsoft/aspire.dev using this priority order, stopping at the first match:

1. The source PR's milestone
2. The milestone of any issue linked via Closes/Fixes/Resolves #N in the PR body
3. The PR's base branch, if it matches release/X.Y or release/X.Y.Z
4. Fallback: main

Milestone titles are normalized with the regex ^v?(\d+)\.(\d+)(?:\.(\d+))?, so:

• 13.3, 13.3 - Preview 1, v13.3 → release/13.3
• 13.2.1, v13.2.1 → release/13.2.1

If the resolved release/X.Y[.Z] branch does not yet exist on microsoft/aspire.dev, the agent creates it from the current tip of main on aspire.dev via the Git refs API (using the same ASPIRE_BOT app-token flow already wired up). The resolved branch is then passed to the create_pull_request safe output via its base field, and surfaced in both the draft PR description and the follow-up comment on the source PR.

Scope constraints honored

The GH App token flow (ASPIRE_BOT_APP_ID / ASPIRE_BOT_PRIVATE_KEY) is org-required and non-trivial to configure, so this change is deliberately minimal on the YAML side:

• Untouched: all four github-app: blocks (top-level checkout: × 2, tools.github, safe-outputs), permissions, tools, network, and the "Configure mirrored target repo Git credentials" step.
• Single YAML change: safe-outputs.steps → "Mirror target repo checkout" → ref: simplified from the source-PR-base expression (which previously resolved to the source aspire PR's base, unrelated to aspire.dev's branch structure) to main. The dynamic base branch is now communicated through the safe output's base field.

All remaining edits are in the Markdown prompt body: new Step 2 ("Determine Target Branch"), new Step 3 ("Ensure the Target Branch Exists"), subsequent steps renumbered, and the draft PR/source PR comment instructions updated to include the resolved base branch.

Validation

• gh aw compile pr-docs-check → 0 errors, 0 warnings.
• Lock file regenerated; manual inspection confirms the mirror step now uses ref: main and app-token configuration is preserved.

Fixes # (issue)

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire.dev issue:
      • New issue
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 16268

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 16268"

[Copilot]

Pull request overview

Updates the pr-docs-check agentic workflow so docs PRs created in microsoft/aspire.dev can be targeted at the appropriate release branch (derived from milestones / linked issues / PR base), rather than always defaulting to main.

Changes:

• Expanded the workflow prompt to resolve a target aspire.dev base branch using milestone/issue/base-branch heuristics and (if needed) create the branch on aspire.dev.
• Simplified the safe-outputs mirror checkout to seed from aspire.dev main.
• Regenerated the compiled workflow lockfile and refreshed action pins (gh-aw v0.68.3, updated container images, etc.).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
.github/workflows/pr-docs-check.md	Updates the agent prompt and changes the mirror checkout ref to main.
.github/workflows/pr-docs-check.lock.yml	Regenerated compiled workflow with updated pins and the new mirror checkout ref: main.
.github/aw/actions-lock.json	Updates the locked github/gh-aw-actions/setup version to v0.68.3.

[Copilot]

The prompt instructs the agent to set a base field on the create_pull_request safe output, but the compiled safe-outputs schema in pr-docs-check.lock.yml only supports fields like branch, title, and body (no base). This will likely cause the agent output to be rejected/ignored and the PR will still target whatever default base the handler uses. Update the workflow/tooling so create_pull_request supports a base input, or change the approach to select the base branch via a supported mechanism (e.g., checkout the desired base in the safe-outputs job before PR creation).

[IEvangelist]

Thanks for the sharp review — both reviewer threads were correct. Confirmed by reading gh-aw source (pkg/workflow/create_pull_request.go and pkg/workflow/compiler_safe_outputs_steps.go): the agent-side create_pull_request schema accepts only body, branch, draft, labels, repo, title — no base field. Per-PR base selection from the agent isn't supported today.

Pushed an update (e7e639b) that pivots to the supported mechanism:

• Uses the workflow-level safe-outputs.create-pull-request.base-branch config, set to ${{ github.base_ref || github.event.pull_request.base.ref || github.event.repository.default_branch }}. gh-aw passes this expression through literally into the injected safe-outputs "Checkout repository" step's ref:, so Actions evaluates it at runtime.
• Result: a PR merged into aspire release/X.Y produces a docs PR targeting release/X.Y on aspire.dev; a PR merged into main targets main. This covers the main "aspire.dev main tracks latest bits" concern the change set out to solve.
• Removed the invalid "emit base:" instruction from the agent prompt and the now-unused milestone → release-branch resolution steps. Added an explicit note telling the agent NOT to attempt a base field.
• The mirror-checkout ref: in safe-outputs.steps now uses the same expression so the mirrored workspace aligns with the PR target branch.
• The GH App token flow (ASPIRE_BOT_APP_ID / ASPIRE_BOT_PRIVATE_KEY) is untouched.

One remaining limitation this approach doesn't cover: an aspire PR merged to main but milestoned to an earlier release (e.g., back-port scenarios). Handling that would require an upstream gh-aw change to accept a per-PR base on the create_pull_request tool. Happy to file an issue with the github/gh-aw project if we want to pursue it later.

[IEvangelist]

Closing this PR without merging.

After working through the reviewer feedback, we confirmed the approach here can't actually deliver what we originally set out to do: target the aspire.dev docs PR based on the source aspire PR's milestone (e.g., milestone 13.3 → release/13.3, 13.2.1 → release/13.2.1).

The current gh-aw create_pull_request safe output doesn't support a per-run base branch:

• The agent-side tool schema accepts only body, branch, draft, labels, repo, title — no base field.
• The workflow-level base-branch is a compile-time string. GitHub Actions expressions are allowed but can't do regex normalization of milestone titles or API lookups to ensure the release branch exists.

Filed a feature request upstream capturing the use case, the limitation, and a few possible designs: github/gh-aw#26908.

Will revisit once that lands (or with a post-handler retarget workaround if the upstream issue stalls). Closing for now to keep the review queue clean.