PR Documentation Check fails to create docs PRs for release branches

[IEvangelist]

Is there an existing issue for this?

• I have searched the existing issues

The generated reports #18993 and #19023 capture individual failures, but not the shared root cause or repository-level fix.

Describe the bug

PR Documentation Check can author and commit the required documentation in microsoft/aspire.dev, but then fails to create the draft docs PR when the effective target is a release/* branch.

The affected runs use gh-aw v0.79.8. The agent correctly calls create_pull_request with an allowlisted base such as release/13.5, but gh-aw patch generation ignores that per-call base and instead uses the workflow's static safe-outputs.create-pull-request.base-branch value, currently main.

Because Aspire checks out the release/13.5 tip at depth 1, git merge-base origin/main <agent-commit> cannot traverse from the shallow release tip to a common ancestor. Patch generation returns ERR_SYSTEM, so the prepared documentation never reaches a PR. Simply changing to full history is unsafe: once the merge-base becomes reachable, a main-based patch could include the entire main-to-release divergence rather than only the agent's documentation commit.

Observed examples include:

• PR #18442
• PR #18566
• PR #18737
• PR #18980
• PR #18981
• PR #19007

Expected Behavior

Patch generation should use the same effective microsoft/aspire.dev branch selected by the workflow's target resolver and passed by the agent. A depth-1 release checkout should then be sufficient because its tip is the correct patch base, and the workflow should create a draft docs PR targeting that branch.

Steps To Reproduce

1. Merge or manually dispatch PR Documentation Check for a source PR whose effective docs target resolves to release/13.5.
2. Let the agent author and commit documentation in the depth-1 microsoft/aspire.dev checkout.
3. Observe the agent call create_pull_request with base: "release/13.5".
4. Observe patch generation use configured main instead and fail while computing the merge-base.

The repository fix is to expose the resolver's effective branch as a step output and use that output for agent-time create-pull-request.base-branch, retaining main as the separate safe-output job fallback. All gh-aw workflow sources should be recompiled together whenever the compiler is run or upgraded.

Exceptions (if any)

Pinned SHA ... failed to generate patch: ERR_SYSTEM: Git command failed with status 1

Aspire doctor output

N/A — this is a GitHub Actions/gh-aw workflow failure.

Anything else?

The upstream dynamic-base defect is already tracked by github/gh-aw#41265 and remains open. The v0.85.4 tag still chooses patch generation's base from the static prConfig.base_branch instead of the agent entry's per-call base.

The separate repository re-shallowing defect github/gh-aw#50240 was fixed by github/gh-aw#50378 in prerelease v0.85.0+, but that fix does not make patch generation honor the per-call base. Therefore, upgrading alone does not resolve this issue.

Compiler update

gh-aw v0.85.4 became the latest stable release on August 6. It contains the separate re-shallowing fix from github/gh-aw#50378 plus security hardening, so the repository fix will upgrade and recompile all eight gh-aw workflows together. The dynamic-base defect remains, so the resolver-output workaround is still required; upgrading without that workaround does not fix docs PR creation.

Impact inventory and recovery tracking

A repository-wide scan of aspire-repo-bot[bot] comments carrying pr-docs-check:notify-source-pr, supplemented by generated gh-aw failure issues, found 35 deduplicated failures after the previous checkout-placement fix #18320 merged. Every affected source PR is merged with milestone 13.5. All 35 authored documentation and then failed during create_pull_request patch generation against the shallow/grafted release/13.5 checkout.

Current recovery state: 19 recovered and 16 pending. The repository, safe-output permission, and cached Copilot CLI staging fixes #19055, #19062, and #19109 are merged. A checked item means the resulting Aspire docs PR is merged or the run conclusively required no docs. Remaining items require a fresh workflow_dispatch from current main.

• #18407 — original run · recovery run · recovered by merged aspire.dev#1433
• #18522 — original run · recovery run · recovered by merged aspire.dev#1434
• #18539 — original run · recovery run · recovered by merged aspire.dev#1435; repository workaround #19109 covers unreleased upstream fix github/gh-aw#50908
• #18580 — original run · recovery run · recovered by merged aspire.dev#1436
• #18009 — run · failure report · recovered by aspire.dev#1229
• #18442 — original run · recovery run · recovered by merged aspire.dev#1437
• #16929 — run · failure report · recovered by aspire.dev#1328
• #18574 — original run · recovery run · recovered by merged aspire.dev#1438
• #18566 — original run · recovery run · recovered by merged aspire.dev#1439
• #18624 — original run · recovery run · recovered by merged aspire.dev#1440
• #18738 — original run · recovery run · recovered by merged aspire.dev#1441
• #18726 — original run · recovery run · recovered by merged aspire.dev#1442
• #18737 — original run · recovery run · recovered by merged aspire.dev#1443
• #18527 — run · failure report · recovered by aspire.dev#1382
• #18829 — original run · recovery run · recovered by merged aspire.dev#1444
• #18718 — run · failure report · recovered by aspire.dev#1387
• #18827 — original run · recovery run · recovered by merged aspire.dev#1445
• #18851 — original run · recovery run · recovered by merged aspire.dev#1446
• #18867 — original run · recovery run · recovered by merged aspire.dev#1447
• #18868 — run · failure report
• #18863 — run · failure report
• #18969 — run · failure report
• #18981 — run · failure report
• #18978 — run · failure issue #18993
• #18980 — run · failure report
• #18943 — run · failure report
• #18991 — run · failure report
• #18992 — run · failure report
• #19007 — run · failure report
• #18985 — run · failure report
• #18918 — run · failure report · failure issue #19023
• #18850 — run · failure report
• #18986 — run · failure report
• #18728 — run · failure report
• #19043 — run · failure report

Seven older release/13.4 failures have now been audited:

• #17177 — superseded; the requested capture-profile documentation covered hidden/internal functionality, and the related replacement aspire.dev#1357 was intentionally closed after maintainers agreed it should not be documented.
• #17235 — still actionable; current aspire update docs do not cover staging refusal on daily/local/PR builds or the overrideStagingFeed escape hatch.
• #17361 — recovered by merged aspire.dev#1127, which added the parser-backed AppHost/resource detection release-note coverage.
• #17387 — still actionable; current local-provisioning docs do not cover ITokenCredentialProvider or accessing Aspire's provisioning credential.
• #17447 — still actionable; current certificate-trust docs do not cover the non-interactive Linux partial-trust success behavior.
• #16686 — still actionable; current aspire run/aspire start docs do not cover ASPIRE_CLI_START_TIMEOUT.
• #17094 — still actionable; current eventing docs do not state that subscription event types must be concrete or document the interface/abstract-type ArgumentException.

The five actionable legacy items will be recovered sequentially after the release/13.5 queue. Because release/13.4 no longer exists in microsoft/aspire.dev, the target resolver will use the latest available release branch.

Closure criteria

• Merge implementation PR #19055 with the full v0.85.4 workflow recompilation.
• Freshly dispatch every unchecked release/13.5 source PR above.
• Link each generated Aspire docs PR (or a successful run that determines no update remains necessary).
• Merge or intentionally close every follow-up with the reason recorded here.
• Triage the seven legacy release/13.4 failures as recovered, superseded, or still actionable.
• Recover or intentionally resolve the five actionable legacy failures.
• Close generated symptom issues [aw] PR Documentation Check reported incomplete result #18993 and [aw] PR Documentation Check reported incomplete result #19023 after their corresponding documentation outcomes are recorded.

[IEvangelist]

Implementation is now available in draft PR #19055. It applies the runtime patch-base workaround, preserves shallow checkouts, removes the duplicate release-support checkout, and recompiles all eight workflows with stable gh-aw v0.85.4. After merge, each unchecked source PR in the inventory needs a fresh workflow dispatch; old job reruns reuse the prior workflow revision.

[IEvangelist]

Sequential recovery monitoring started after #19055 merged. Manual dispatches share one main concurrency group with cancel-in-progress: true, so recoveries will run one at a time to avoid cancelling each other. This issue will remain open while each new run and resulting Aspire docs PR is reconciled.

[IEvangelist]

Recovery 1/31: dispatched source PR #18407 as run 31116010823. The next recovery will not be dispatched until this run completes.

[IEvangelist]

Recovery 1/31 exposed a second gh-aw v0.85.4 defect after the dynamic-base fix worked:

• Run 31116010823 generated the correct release/13.5 docs patch; agent, detection, and safe-output processing all reached the expected code path.
• The safe-output app token was minted with contents: read, so signed ref creation and fallback git push both returned 403. gh-aw created fallback aspire.dev#1432.
• The run's final red status came from the notification job attempting to comment on locked source PR Stop listing agent-skill snippets as AppHosts #18407.

Root cause is filed as github/gh-aw#50905: checkout auto-detection overwrites the stronger handler-derived contents permission. Follow-up draft PR #19062 removes the redundant custom safe-output checkouts from both cross-repository docs workflows and recompiles all eight workflows; the generated app tokens return to permission-contents: write.

Recovery dispatches are paused until #19062 merges. Then #18407 will be retried first, fallback issue #1432 reconciled, and the sequential queue will continue.

[IEvangelist]

Actions is operational again. Retried source PR #18407 from merged main: https://github.com/microsoft/aspire/actions/runs/31133691938

[IEvangelist]

Recovery stack #19118 and #19155 is now merged into main as e35ca6eb41a72d3826892363189f74ca0fff7a6c and 15521acc38abbda0a292ed66539ebf964b31dcbd.

The merged fix closes the false-green gap in two layers: target checkout and release enumeration now use the authoritative microsoft/aspire.dev refs and fail closed, while the workflow now requires a trusted conclusive safe-output outcome (drafted or skipped) instead of treating a green agent job as recovery success. Both exact heads completed full CI and clean zero-comment Copilot reviews before merge.

Sequential recovery can now resume with #18868. A workflow run will count only when its trusted safe-output evidence identifies a created docs PR or a conclusive no-docs-needed skip.

[IEvangelist]

Recovery resumed: source PR #18868 is running as 31506420474 from merged main revision 15521ac. Its prior false-green run and notification remain preserved in the audit record. No further manual recovery will be dispatched until this run produces trusted safe-output evidence of a docs PR or conclusive skip.

[IEvangelist]

Recovery #18868 is reconciled as a conclusive skip from run 31506420474. The trusted outcome validator passed, the safe-output manifest contained only
otify_source_pr, and the source PR received the canonical no-docs-needed explanation. No aspire.dev PR was created and the authoritative
elease/13.5 baseline remained unchanged.

[IEvangelist]

Release/13.5 recovery #18863 is queued as run 31507332225 from merged main. Its prior shallow-clone draft failure (run 30491297177) remains preserved. No next manual recovery will dispatch until #18863 yields a trusted docs PR or conclusive skip.