diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 4ff9d73f021..803678d211f 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -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/). @@ -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. diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md index 07bb4775d13..2e2aed1ac66 100644 --- a/docs/src/content/docs/reference/triggers.md +++ b/docs/src/content/docs/reference/triggers.md @@ -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