[docs] Update documentation for features from 2026-02-22#17647
Conversation
github-actions
bot
added
automation
documentation
|
✅ Pull request created: #17647 |
There was a problem hiding this comment.
Pull request overview
Updates user-facing documentation to reflect recently merged behavior changes in gh aw audit and safe-outputs processing.
Changes:
- Document
gh aw auditimprovements: surfacing pre-agent failure step errors and returning clearer errors when a run ID can’t be fetched. - Document
add-commentmention behavior: preserving the parent issue/PR/discussion author as an allowed mention. - Document fail-fast behavior for code-push safe outputs: cancelling subsequent non-code-push outputs and surfacing failure context in the conclusion job’s failure issue/comment.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/src/content/docs/setup/cli.md | Adds documentation for improved audit error surfacing and clearer “run not found” style errors. |
| docs/src/content/docs/reference/safe-outputs.md | Adds docs for add-comment mention preservation and fail-fast cancellation behavior after code-push failures. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level (job logs, specific step, or first failing step). | ||
|
|
||
| When a workflow fails before the agent executes (for example, due to lockdown validation failures, missing secrets, or binary install failures), the audit report surfaces the actual error from the workflow step log files. The `failure_analysis.error_summary` field reflects the specific failure message rather than reporting "No specific errors identified". Providing an invalid run ID returns a human-readable error instead of a raw exit code. |
There was a problem hiding this comment.
The CLI now returns a human-readable error specifically when the workflow run ID is not found (404/Not Found). The wording here says “invalid run ID”, which could be read as a format/parse error. Consider rephrasing to “non-existent run ID” / “run ID not found” (and optionally note this can also happen if you don’t have repo access), to match the actual behavior.
| When a workflow fails before the agent executes (for example, due to lockdown validation failures, missing secrets, or binary install failures), the audit report surfaces the actual error from the workflow step log files. The `failure_analysis.error_summary` field reflects the specific failure message rather than reporting "No specific errors identified". Providing an invalid run ID returns a human-readable error instead of a raw exit code. | |
| When a workflow fails before the agent executes (for example, due to lockdown validation failures, missing secrets, or binary install failures), the audit report surfaces the actual error from the workflow step log files. The `failure_analysis.error_summary` field reflects the specific failure message rather than reporting "No specific errors identified". Providing a non-existent run ID, or a run ID for a repository you don't have access to, returns a human-readable error instead of a raw exit code. |
| allowed-reasons: [outdated] # restrict hiding reasons (optional) | ||
| ``` | ||
|
|
||
| The author of the parent issue, PR, or discussion receiving the comment is automatically preserved as an allowed mention. This means `@username` references to the issue/PR/discussion author are not neutralized when the workflow posts a reply. |
There was a problem hiding this comment.
This states the parent issue/PR/discussion author is “automatically preserved as an allowed mention”. In the implementation, bot authors are intentionally excluded from the allowlist, so @bot-author mentions may still be neutralized. Consider clarifying this (e.g., “non-bot author”) to avoid overstating the guarantee.
| The author of the parent issue, PR, or discussion receiving the comment is automatically preserved as an allowed mention. This means `@username` references to the issue/PR/discussion author are not neutralized when the workflow posts a reply. | |
| The non-bot author of the parent issue, PR, or discussion receiving the comment is automatically preserved as an allowed mention. This means `@username` references to that non-bot issue/PR/discussion author are not neutralized when the workflow posts a reply; mentions of bot authors may still be neutralized. |
|
|
||
| #### Fail-Fast on Code Push Failure | ||
|
|
||
| If `push-to-pull-request-branch` (or `create-pull-request`) fails, the safe-output pipeline cancels all remaining non-code-push outputs. Each cancelled output is marked with an explicit reason such as "Cancelled: code push operation failed". The failure details appear in the agent failure issue or comment generated by the conclusion job. |
There was a problem hiding this comment.
The cancellation reason in output results includes the failing code-push type and error (e.g., "Cancelled: code push operation failed (push_to_pull_request_branch: Branch not found)"). The docs’ example reason omits that detail; consider mentioning that the reason typically includes the failing output type + error to make it easier for users to recognize what failed.
| If `push-to-pull-request-branch` (or `create-pull-request`) fails, the safe-output pipeline cancels all remaining non-code-push outputs. Each cancelled output is marked with an explicit reason such as "Cancelled: code push operation failed". The failure details appear in the agent failure issue or comment generated by the conclusion job. | |
| If `push-to-pull-request-branch` (or `create-pull-request`) fails, the safe-output pipeline cancels all remaining non-code-push outputs. Each cancelled output is marked with an explicit reason, typically including the failing code-push type and error, such as `Cancelled: code push operation failed (push_to_pull_request_branch: Branch not found)`. The failure details also appear in the agent failure issue or comment generated by the conclusion job. |
1 participant
Documentation Updates - 2026-02-22
This PR updates the documentation based on user-facing features merged in the last 24 hours.
Features Documented
auditerror surfacing for pre-agent failures (from fix(audit): surface pre-agent step errors when agent never executed #17623)add-comment(from Allow parent issue/PR/discussion author as an allowed mention in add_comment #17628)Changes Made
docs/src/content/docs/setup/cli.mdto document thatgh aw auditnow surfaces actual error messages from workflow step logs when the agent never executed, and returns a human-readable error for invalid run IDs.docs/src/content/docs/reference/safe-outputs.md—add-commentsection to document that the parent issue/PR/discussion author is automatically preserved as an allowed mention.docs/src/content/docs/reference/safe-outputs.md—push-to-pull-request-branchsection to document the new fail-fast behavior: when a code-push output fails, all remaining non-code-push outputs are cancelled with an explicit reason, and the failure context appears in the agent failure issue/comment.Merged PRs Referenced
Notes
Other PRs merged in this period (#17641 jsweep cleanup, #17626 docs unbloat, #17605 parser log update, #17557 error codes, #17576 triage fork-only, #17558 Gemini diagnostics) were either internal/infrastructure changes or already-merged documentation updates that do not require additional user-facing documentation.