Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
48 changes: 48 additions & 0 deletions docs/src/content/docs/reference/safe-outputs.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,9 @@ This declares that the workflow should create at most one new issue.
| **Create Discussion** | `create-discussion:` | Create GitHub discussions | 1 | ✅ |
| **Create Agent Task** | `create-agent-task:` | Create Copilot agent tasks | 1 | ✅ |
| **Push to PR Branch** | `push-to-pull-request-branch:` | Push changes to PR branch | 1 | ❌ |
| **Update Release** | `update-release:` | Update GitHub release descriptions | 1 | ✅ |
| **Code Scanning Alerts** | `create-code-scanning-alert:` | Generate SARIF security advisories | unlimited | ❌ |
| **No-Op** | `noop:` | Log completion message for transparency (auto-enabled) | 1 | ❌ |
| **Missing Tool** | `missing-tool:` | Report missing tools (auto-enabled) | unlimited | ❌ |

Custom safe output types: [Custom Safe Output Jobs](/gh-aw/guides/custom-safe-outputs/).
Expand Down Expand Up @@ -200,6 +202,52 @@ safe-outputs:

When `create-pull-request` or `push-to-pull-request-branch` are enabled, file editing tools (Edit, Write, NotebookEdit) and git commands are automatically added.

### Release Updates (`update-release:`)

Updates GitHub release descriptions with three operations: replace, append, or prepend content.

```yaml wrap
safe-outputs:
update-release:
max: 1 # Optional: max releases (default: 1, max: 10)
target-repo: "owner/repo" # Optional: cross-repository
github-token: ${{ secrets.CUSTOM_TOKEN }} # Optional: custom token
```

**Operations:**
- **replace** - Completely replaces the release body
- **append** - Adds content to the end with separator and AI attribution
- **prepend** - Adds content to the start with AI attribution and separator

**Agent Output Format:**
```jsonl
{"type": "update_release", "tag": "v1.0.0", "operation": "replace", "body": "New content"}
{"type": "update_release", "tag": "v2.0.0", "operation": "append", "body": "Additional notes"}
{"type": "update_release", "operation": "prepend", "body": "Summary (tag inferred)"}
```

The `tag` field is optional when triggered by release events (automatically inferred from context). The workflow needs read access to releases; only the generated job receives write permissions.

### No-Op Logging (`noop:`)

Enabled by default with any safe-outputs configuration. Allows agents to produce human-visible completion messages when no actions are needed, ensuring workflows never complete silently.

```yaml wrap
safe-outputs:
create-issue: # noop enabled automatically
noop: false # Or explicitly disable
# noop:
# max: 1 # Or configure max messages (default: 1)
```

**Agent Output Format:**
```jsonl
{"type": "noop", "message": "Analysis complete - no issues found"}
{"type": "noop", "message": "No changes needed, code follows best practices"}
```

Messages are displayed in the workflow conclusion comment (when reaction configured) or step summary. This provides transparency and prevents confusion from silent workflow completion.

### Missing Tool Reporting (`missing-tool:`)

Enabled by default with any safe-outputs configuration. Automatically detects and reports tools lacking permissions or unavailable functionality.
Expand Down
43 changes: 43 additions & 0 deletions docs/src/content/docs/reference/triggers.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,49 @@ The `manual-approval` field sets the `environment` on the activation job, enabli

The field accepts a string environment name that must match a configured environment in the repository. Configure approval rules, required reviewers, and wait timers in repository Settings → Environments. See [GitHub's environment documentation](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) for environment configuration details.

### Skip-If-Match Condition (`skip-if-match:`)

Conditionally skip workflow execution when a GitHub search query has matches. Useful for preventing duplicate scheduled runs or waiting for prerequisites.

```yaml wrap
on:
schedule:
- cron: "0 13 * * 1-5"
skip-if-match: 'is:issue is:open in:title "[daily-report]"'
```

**How it works:**
1. A pre-activation check runs the search query against the current repository
2. If matches are found, the workflow is skipped (activation job returns false)
3. The query is automatically scoped to the current repository

**Common Use Cases:**

Prevent duplicate scheduled reports:
```yaml wrap
on:
schedule:
- cron: "0 9 * * 1"
skip-if-match: 'is:issue is:open label:weekly-summary'
```

Wait for deployment PRs to close:
```yaml wrap
on:
workflow_dispatch:
skip-if-match: "is:pr is:open label:deployment"
```

Skip if processing queue is full:
```yaml wrap
on:
schedule:
- cron: "0 */6 * * *"
skip-if-match: "is:issue is:open label:needs-processing"
```

The search uses GitHub's issue/PR search API with efficient `per_page=1` query. Supports all standard GitHub search qualifiers (`is:`, `label:`, `in:title`, `author:`, etc.).

## Related Documentation

- [Command Triggers](/gh-aw/reference/command-triggers/) - Special @mention triggers and context text
Expand Down
Loading