Skip to content

[docs] docs: remove bullet-list bloat from ephemerals guide #19141

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 2 commits into from
Mar 2, 2026
Merged

[docs] docs: remove bullet-list bloat from ephemerals guide #19141

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
09f0ed8
docs: remove bullet-list bloat from ephemerals guide
web-flow Mar 2, 2026
f00b951
ci: trigger CI checks
github-actions[bot] Mar 2, 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
74 changes: 6 additions & 68 deletions docs/src/content/docs/guides/ephemerals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,7 @@ GitHub Agentic Workflows includes several features designed to automatically exp

## Why Use Ephemerals?

**Cost Control**: Scheduled workflows can accumulate costs over time. Setting expiration dates ensures they stop automatically after a deadline.

**Reduce Clutter**: AI-generated issues and discussions can accumulate quickly. Auto-expiration removes obsolete content, keeping your repository focused on active work.

**Status Updates**: When workflows post status updates repeatedly, hiding older comments prevents timeline clutter while preserving the latest information.

**Clean Automation**: Prevent automated content from overwhelming your main repository by using separate repositories and controlling cross-references.
Ephemerals control costs by stopping scheduled workflows at deadlines, reduce clutter by auto-expiring issues and discussions, keep status timelines clean by hiding older comments, and isolate automation via the SideRepoOps pattern.

## Expiration Features

Expand All @@ -34,17 +28,7 @@ on: weekly on monday

The minimum granularity is hours - minute-only units (e.g., `+30m`) are not allowed. Recompiling the workflow resets the stop time.

**Key behaviors**:
- The workflow is disabled at the specified deadline, preventing new runs
- Existing runs continue to completion
- The stop time is preserved during recompilation unless `--refresh-stop-time` flag is used
- Use `gh aw compile --refresh-stop-time` to regenerate the stop time based on current time

**Use cases**:
- Trial workflows that should run for a limited period
- Experimental features with automatic sunset dates
- Orchestrated initiatives with defined end dates
- Cost-controlled scheduled workflows
At the deadline, new runs are prevented while existing runs complete. The stop time persists through recompilation; use `gh aw compile --refresh-stop-time` to reset it. Common uses: trial periods, experimental features, orchestrated initiatives, and cost-controlled schedules.
Comment on lines 29 to +31
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

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

The stop-after section is internally inconsistent: it says recompiling resets the stop time, but the next paragraph says the stop time persists unless --refresh-stop-time is used. The compiler tests indicate the stop time is preserved by default and only refreshed when --refresh-stop-time is set (see pkg/workflow/stop_after_test.go). Please update the earlier sentence (and/or reword this section) so recompilation behavior is described consistently and matches actual behavior.

See below for a potential fix:

The minimum granularity is hours - minute-only units (e.g., `+30m`) are not allowed. For relative deltas, the stop time is calculated once at compilation time and stored in the compiled workflow.

At the deadline, new runs are prevented while existing runs complete. By default, the stop time persists through recompilation; use `gh aw compile --refresh-stop-time` to recompute it from the current time. Common uses: trial periods, experimental features, orchestrated initiatives, and cost-controlled schedules.

Copilot uses AI. Check for mistakes.

See [Triggers Reference](/gh-aw/reference/triggers/#stop-after-configuration-stop-after) for complete documentation.

Expand Down Expand Up @@ -113,21 +97,7 @@ safe-outputs:
close-older-issues: true # Close previous reports
```

**How it works**:
- When a new issue is created successfully, the system searches for older issues
- Matches are identified by the workflow-id marker embedded in the issue body
- Up to 10 older issues are closed as "not planned"
- Each closed issue receives a comment linking to the new issue
- Only runs if the new issue creation succeeds

**Requirements**:
- GH_AW_WORKFLOW_ID environment variable must be set
- Requires appropriate permissions on the target repository

**Use cases**:
- Weekly status reports where only the latest matters
- Recurring analysis workflows that supersede previous results
- Scheduled summaries that replace older versions
When a new issue is created, up to 10 older issues with the same workflow-id marker are closed as "not planned" with a comment linking to the new issue. Requires `GH_AW_WORKFLOW_ID` to be set and appropriate repository permissions. Ideal for weekly reports and recurring analyses where only the latest result matters.
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

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

This paragraph says GH_AW_WORKFLOW_ID must be set as a requirement. In compiled workflows it’s set automatically at the safe-outputs job level (see pkg/workflow/compiler_safe_outputs_job.go where GH_AW_WORKFLOW_ID is always populated), so framing it as a user requirement is potentially misleading. Consider rephrasing to clarify it’s provided automatically by gh aw (or remove the requirement line entirely and just describe the workflow-id marker behavior).

Suggested change
When a new issue is created, up to 10 older issues with the same workflow-id marker are closed as "not planned" with a comment linking to the new issue. Requires `GH_AW_WORKFLOW_ID` to be set and appropriate repository permissions. Ideal for weekly reports and recurring analyses where only the latest result matters.
When a new issue is created, `gh aw` uses the workflow-id marker (`GH_AW_WORKFLOW_ID`, which is set automatically in compiled workflows) to find and close up to 10 older issues as "not planned" with a comment linking to the new issue. This feature requires appropriate repository permissions and is ideal for weekly reports and recurring analyses where only the latest result matters.

Copilot uses AI. Check for mistakes.

## Noise Reduction Features

Expand All @@ -142,27 +112,7 @@ safe-outputs:
allowed-reasons: [outdated] # Optional: restrict hiding reasons
```

**How it works**:
- Before posting a new comment, searches for previous comments from the same workflow
- Identifies comments by `GITHUB_WORKFLOW` name
- Hides (minimizes) matching comments in the GitHub UI
- Posts the new comment
- Only hides comments; does not delete them

**Allowed reasons**:
- `spam` - Mark as spam
- `abuse` - Mark as abusive
- `off_topic` - Mark as off-topic
- `outdated` - Mark as outdated (default)
- `resolved` - Mark as resolved

Configure `allowed-reasons` to restrict which reasons can be used. If omitted, only `outdated` is allowed by default.

**Use cases**:
- Workflows posting status updates repeatedly
- Build status notifications where only latest result matters
- Health check workflows reporting periodic results
- Progress tracking workflows with frequent updates
Before posting, the system finds and minimizes previous comments from the same workflow (identified by `GITHUB_WORKFLOW`). Comments are hidden, not deleted. Use `allowed-reasons` to restrict which minimization reason is applied: `spam`, `abuse`, `off_topic`, `outdated` (default), or `resolved`. Useful for status updates, build notifications, and health checks where only the latest result matters.
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

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

The allowed-reasons explanation could be more precise about defaults/semantics. The code and changelog indicate that if allowed-reasons is omitted, all reasons are allowed (see pkg/workflow/add_comment.go comment and CHANGELOG entry). Consider adjusting the wording so it’s clear allowed-reasons is an allowlist (optional), and that omission doesn’t restrict reasons.

Copilot uses AI. Check for mistakes.

See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#hide-older-comments) for complete documentation.

Expand Down Expand Up @@ -207,14 +157,7 @@ safe-outputs:
| **Auto-close** | Supported with maintenance workflow | Supported with maintenance workflow |
| **Timeline noise** | Can clutter project tracking | Separate from development work |

**Use cases for ephemeral discussions**:

- Weekly status reports
- Periodic analysis results
- Temporary announcements
- Q&A that expires
- Time-bound experiments
- Community updates
Ephemeral discussions work well for weekly reports, periodic analyses, temporary announcements, time-bound Q&A, and community updates.

**Combining features**:

Expand All @@ -226,12 +169,7 @@ safe-outputs:
close-older-discussions: true # Replace previous reports
```

This configuration ensures:

1. Only the latest weekly status discussion is open
2. Previous reports are closed when new ones are created
3. All discussions auto-close after 14 days
4. The "Status Updates" category stays clean and focused
This keeps the "Status Updates" category clean: previous reports are closed on creation and all discussions auto-close after 14 days.

## Related Documentation

Expand Down