[docs] docs: unbloat safe outputs reference#42814
Conversation
github-actions
Bot
added
automation
doc-unbloat
documentation
|
👋 Nice work from the Documentation Unbloat workflow — this is a clean, focused tightening of the The PR is well-scoped (single file, single purpose), clearly described, and labels are accurate. No issues to flag — this looks ready for review. 🟢
|
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. Test Quality Sentinel skipped. |
|
✅ PR Code Quality Reviewer completed the code quality review. |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR does not have the 'implementation' label and has ≤100 new lines of code in business logic directories. |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
There was a problem hiding this comment.
Pull request overview
This PR tightens the safe outputs reference docs by removing repetitive scaffolding and consolidating several configuration sections into concise prose, while keeping examples and links intact.
Changes:
- Added a brief intro clarifying which safe output types are always available vs conditionally auto-injected.
- Condensed
group,close-older-issues, andgroup-by-daydocumentation into shorter paragraphs.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/safe-outputs.md | Condenses safe output handler descriptions and adds a short intro about built-in/auto-injected handlers. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 3
- Review effort level: Low
| - Parent issues include metadata tracking all sub-issues | ||
|
|
||
| This is useful for workflows that create multiple related issues, such as planning workflows that break down epics into tasks, or batch processing workflows that create issues for individual items. | ||
| The `group` field (default: `false`) organizes multiple issues as sub-issues under a parent issue. The parent is managed using the workflow ID as the group identifier, children are linked through GitHub sub-issue relationships, each parent can hold up to 64 sub-issues, and the parent stores metadata for the tracked children. This is useful for workflows that create sets of related issues, such as plans broken into tasks or batch processing runs. |
There was a problem hiding this comment.
Fixed — the description now states the parent is identified by a <!-- gh-aw-group: ... --> marker derived from the workflow name, and the false "stores metadata for tracked children" claim has been removed (children are linked via GitHub sub-issue relationships only).
| #### Auto-Close Older Issues | ||
|
|
||
| The `close-older-issues` field (default: `false`) automatically closes previous open issues from the same workflow when a new issue is created. This is useful for workflows that generate recurring reports or status updates, ensuring only the latest issue remains open. | ||
| The `close-older-issues` field (default: `false`) closes previous open issues from the same workflow after a new issue is created. It searches for open issues with the same workflow-id marker, closes up to 10 of them as "not planned," and adds a comment linking to the new issue. The cleanup runs only if new issue creation succeeds, which makes it a good fit for recurring reports or status updates where only the latest issue should remain open. |
There was a problem hiding this comment.
Fixed — the description now documents close-older-key (uses gh-aw-close-key marker instead of workflow-id markers) and mentions that in reusable-workflow scenarios the gh-aw-workflow-call-id marker is used for precise per-caller matching to prevent cross-caller closes.
| #### Group By Day | ||
|
|
||
| The `group-by-day` field (default: `false`) groups multiple same-day workflow runs into a single issue. When enabled, the handler searches for an existing open issue created **today (UTC)** with the same workflow-id marker (or `close-older-key` if set). If found, the new content is posted as a **comment** on that existing issue instead of creating a new one. | ||
| The `group-by-day` field (default: `false`) groups same-day workflow runs into a single issue. The handler looks for an existing open issue created **today (UTC)** with the same workflow-id marker, or `close-older-key` if set, and posts the new content as a **comment** instead of creating a new issue. This is useful for frequent scheduled workflows, such as runs every four hours, because all runs for the day contribute to one issue. Posting as a comment does not consume a max-count slot; if the pre-check fails, normal issue creation is used as a fallback. |
There was a problem hiding this comment.
Fixed — the description now notes that in reusable-workflow scenarios the gh-aw-workflow-call-id marker is also used for matching (alongside the gh-aw-workflow-id marker, or gh-aw-close-key when close-older-key is set).
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Docs-only change — one non-blocking accuracy concern
The condensed prose and structure improvements are generally sound. One spot in the new intro paragraph uses language that could mislead users about configurability of system outputs — flagged inline. All other content changes preserve the original semantics accurately.
🔎 Code quality review by PR Code Quality Reviewer · 36.6 AIC · ⌖ 9.55 AIC · ⊞ 1.6K
Comment /review to run again
There was a problem hiding this comment.
🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · 40.7 AIC · ⌖ 6.61 AIC · ⊞ 4.9K
| The `group` field (default: `false`) organizes multiple issues as sub-issues under a parent issue. The parent is managed using the workflow ID as the group identifier, children are linked through GitHub sub-issue relationships, each parent can hold up to 64 sub-issues, and the parent stores metadata for the tracked children. This is useful for workflows that create sets of related issues, such as plans broken into tasks or batch processing runs. | ||
|
|
||
| **Example:** | ||
|
|
There was a problem hiding this comment.
Removing the **Example:** label left a double blank line before the code block. One blank line is sufficient — remove one of the two blank lines between the prose paragraph and the ```yaml fence.\n\n@copilot please address this.
There was a problem hiding this comment.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 43.8 AIC · ⌖ 7.11 AIC · ⊞ 6.6K
Comment /matt to run again
|
@copilot please run the
|
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Summary
Refactors
docs/src/content/docs/reference/safe-outputs.mdto reduce verbosity and improve information density in the issue-creation safe-output field reference sections.Changes
docs/src/content/docs/reference/safe-outputs.mdnoop,missing-tool, andmissing-dataare always present;create-issueis auto-injected only when no non-system safe outputs are configured.gh-aw-groupHTML marker derived from the workflow name. Removed the redundant Example subheader.gh-aw-workflow-id(orgh-aw-close-keywhenclose-older-keyis set); reusable-workflow scenarios usegh-aw-workflow-call-idfor per-caller matching to prevent cross-closing; closes up to 10 issues as not planned; cleanup runs only if new issue creation succeeds.gh-aw-workflow-idtogh-aw-workflow-call-idin reusable scenarios togh-aw-close-keyoverride), that comment posts do not consume a max-count slot, and the fallback to normal issue creation if the pre-check fails.Impact
No code, configuration schema, or behaviour changes. Documentation only. Net: -17 lines in 1 file.