From e5c1949a89ab36940c57a2ae14f3c5325911072f Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 19 Nov 2025 06:09:13 +0000 Subject: [PATCH] Update documentation for features from 2025-11-19 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for three new features merged in the last 24 hours: 1. Update-release safe output (PR #4278) - Added to safe outputs table - Full documentation with operations (replace, append, prepend) - Agent output format examples - Configuration options 2. No-op safe output (PR #4286) - Added to safe outputs table - Documentation explaining transparency and auto-enable - Agent output format examples - Use cases for silent completion prevention 3. Skip-if-match trigger condition (PR #4287) - Added to triggers reference - How it works explanation - Three common use case examples - GitHub search query integration details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../content/docs/reference/safe-outputs.md | 48 +++++++++++++++++++ docs/src/content/docs/reference/triggers.md | 43 +++++++++++++++++ 2 files changed, 91 insertions(+) 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