Skip to content

[docs] docs: unbloat safe outputs reference #42814

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 3 commits into from
Jul 2, 2026
+5 −20
Merged

[docs] docs: unbloat safe outputs reference #42814

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
28913ab
docs: unbloat safe outputs reference
github-actions[bot] Jul 1, 2026
acb4fbe
Merge branch 'main' into docs/unbloat-safe-outputs-c9493154ceac1ae3
github-actions[bot] Jul 1, 2026
bd59017
docs: fix group/close-older-issues/group-by-day marker accuracy
Copilot Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 5 additions & 20 deletions docs/src/content/docs/reference/safe-outputs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ The agent requests issue creation; a separate job with `issues: write` creates i

## Available Safe Output Types

The tables below summarize the built-in safe output handlers. `noop`, `missing-tool`, and `missing-data` are always available, and `create-issue` is auto-injected only when no non-system safe outputs are configured.
Comment thread
pelikhan marked this conversation as resolved.
Comment thread
pelikhan marked this conversation as resolved.

### Issues & Discussions

| Output | Key | Description |
Expand Down Expand Up @@ -168,16 +170,8 @@ To explicitly disable expiration (useful when create-issue has a default expirat

#### Issue Grouping

The `group` field (default: `false`) automatically organizes multiple issues as sub-issues under a parent issue. When enabled:

- Parent issues are automatically created and managed using the workflow ID as the group identifier
- Child issues are linked to the parent using GitHub's sub-issue relationships
- Maximum of 64 sub-issues per parent issue
- 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 identified by a `<!-- gh-aw-group: ... -->` marker derived from the workflow name; children are linked through GitHub sub-issue relationships; and each parent can hold up to 64 sub-issues. This is useful for workflows that create sets of related issues, such as plans broken into tasks or batch processing runs.

**Example:**

@github-actions github-actions Bot Jul 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

```yaml wrap
safe-outputs:
Expand All @@ -190,7 +184,7 @@ safe-outputs:

#### 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 using the `gh-aw-workflow-id` marker (or `gh-aw-close-key` when `close-older-key` is set), closes up to 10 of them as "not planned," and adds a comment linking to the new issue. In reusable-workflow scenarios, the `gh-aw-workflow-call-id` marker is used for precise per-caller matching, so issues from different callers sharing the same reusable workflow are not cross-closed. 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.

```yaml wrap
safe-outputs:
Expand All @@ -200,16 +194,9 @@ safe-outputs:
close-older-issues: true
```

When enabled:

- Searches for open issues containing the same workflow-id marker in their body
- Closes found issues as "not planned" with a comment linking to the new issue
- Maximum 10 older issues will be closed
- Only runs if the new issue creation succeeds

#### 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)** using the workflow marker (`gh-aw-workflow-id`, or `gh-aw-workflow-call-id` in reusable-workflow scenarios, or `gh-aw-close-key` when `close-older-key` is 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.

```yaml wrap
safe-outputs:
Expand All @@ -220,8 +207,6 @@ safe-outputs:
group-by-day: true
```

This is useful for scheduled workflows (e.g. every 4 hours) that produce recurring daily reports: all runs on the same day contribute to one issue, eliminating duplicate open/closed issues. The max-count slot is not consumed when posting as a comment; on failure of the pre-check, normal issue creation proceeds as a fallback.

#### Title-Based Deduplication

The `deduplicate-by-title` field drops duplicate issues by comparing titles before creation. Accepts:
Expand Down
Loading