Fix silent breaking-change documentation publication failures

[tarekgh]

Summary

Fix the breaking-change documentation workflow completing successfully without publishing its generated comment.

This occurred after #135277 merged: workflow run 37654155119 generated draft artifacts but published no comment. Required shell commands were denied, and the incomplete outcome did not fail the workflow.

Changes

• Configure one default shallow checkout so the required helper scripts are available, retaining the trusted base context for pull_request_target without checking out the same repository twice.
• Allow the required jq and mkdir commands without granting unrestricted shell access.
• Require the existing version and comment-building helpers, and submit the complete comment through a single-command safe-output invocation.
• Expose the effective dry-run mode in the rendered prompt, with a false fallback for automatic PR events.
• Validate the outcome, PR destination, complete draft pair, and raw comment body against pr-comment.md. Preserve valid early no-ops and dry runs, while rejecting incomplete generation and publication failures.
• Prevent publication unless the generation job succeeds.
• Regenerate the lock file with gh-aw v0.86.2.

Validation

• Strict compilation and schema validation passed for the submitted workflow:

  gh aw compile breaking-change-doc --schedule-seed dotnet/runtime --no-check-update --strict --validate --no-emit

• All 58 session-local regression checks passed, covering the original failed-run output, numeric and string PR identifiers, raw comment-body binding, dry runs, no-op handling, failed-generation publication gating, and single trusted checkout behavior. Seven cases use the exact pinned workflow renderer to verify the effective mode for manual and automatic events. The test snapshot matches both workflow files. These checks are not included in this PR or wired into repository CI.

• Targeted Markdownlint passed for .github/workflows/breaking-change-doc.md.

• git diff --check passed.

Live validation

An initial dry run exposed that the selected dry-run mode was not supplied to the rendered prompt. The validator rejected a comment intent and the publication gate blocked posting. This led to the explicit mode-propagation correction.

A corrected dry run passed on commit 73ea0d33b02 against #135277 with suppress_output=true. The prompt explicitly contained true, both complete documentation artifacts were generated, and the outcome was exactly one noop with no publication intent. All jobs passed and the source PR's four comment IDs remained unchanged.

Commit 4db4d8311d9 addresses the checkout review comment by using the default checkout configuration. The generated agent job now has one repository checkout with persist-credentials: false and fetch-depth: 1. The review thread is resolved.

A final-commit dry run passed against #135277 with suppress_output=true. The single checkout succeeded, both complete draft artifacts were generated, and the raw and ingested outcomes were exactly one noop. All seven jobs passed, and the source PR's four comment IDs remained unchanged.

A publication-enabled run passed on the same final commit with suppress_output=false. All seven jobs, outcome validation, and the publication gate passed. Exactly one raw add_comment intent targeted #135277 and matched the complete helper-generated comment before sanitization.

The workflow actually posted the documentation comment as github-actions[bot]. The source PR's comment count increased from four to five. The published comment was checked to contain the ingested safe-output body and the complete issue draft in its prefilled issue link. No dotnet/docs issue was created.

Scope and limitations

This PR remains a draft. Manual dry-run generation and actual comment publication are verified on the final commit; the automatic merge/label trigger was not exercised by these manual dispatches.

The version helper is invoked, but the sandbox's unauthenticated gh dependency requires its documented metadata fallback. An independent authenticated local execution confirmed .NET 12 Preview 1 with Tentative=false and no backports, matching the generated documentation. This PR does not grant additional GitHub credentials.

PR CI passed Markdownlint, but it does not exercise this workflow's generation/publication path or the session-local regression checks. The main runtime build/test pipelines exclude these .github-only changes.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
15 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/runtime-infrastructure
See info in area-owners.md if you want to be subscribed.

[Copilot]

🔵 Needs a closer look

The write-capable workflow remains live-validation pending, and the checkout configuration currently duplicates repository setup.

1 open finding

• Avoid duplicate repository checkout in generated job · New

What changed in this PR

Hardens breaking-change documentation generation and publication to prevent silent failures.

Changes:

• Checks out helper scripts and permits required commands.
• Validates generated drafts, comment intent, destination, and job outcome.
• Regenerates the compiled gh-aw workflow.

File	Description
.github/​workflows/​breaking-change-doc.md	Adds checkout, validation, publication guidance, and failure gating.
.github/​workflows/​breaking-change-doc.lock.yml	Regenerates the executable workflow.

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The workflow is internally consistent and final live validation successfully published the expected comment.

0 open findings

1 resolved since last review

• Avoid duplicate repository checkout in generated job

🧠 Review effort: Balanced