diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index 8185e071104..75b25159032 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -603,7 +603,6 @@ on: label_command: deploy permissions: contents: read - pull-requests: write # Required for automatic label removal safe-outputs: add-comment: max: 1 diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md index 2308cca3710..d76474021f8 100644 --- a/.github/aw/github-agentic-workflows.md +++ b/.github/aw/github-agentic-workflows.md @@ -79,7 +79,7 @@ The YAML frontmatter supports these fields: - **`on:`** - Workflow triggers (required) - String: `"push"`, `"issues"`, etc. - Object: Complex trigger configuration - - Special: `slash_command:` for /mention triggers (replaces deprecated `command:`) + - Special: `slash_command:` for /mention triggers - **`forks:`** - Fork allowlist for `pull_request` triggers (array or string). By default, workflows block all forks and only allow same-repo PRs. Use `["*"]` to allow all forks, or specify patterns like `["org/*", "user/repo"]` - **`stop-after:`** - Can be included in the `on:` object to set a deadline for workflow execution. Supports absolute timestamps ("YYYY-MM-DD HH:MM:SS") or relative time deltas (+25h, +3d, +1d12h). The minimum unit for relative deltas is hours (h). Uses precise date calculations that account for varying month lengths. - **`reaction:`** - Add emoji reactions to triggering items @@ -186,7 +186,6 @@ The YAML frontmatter supports these fields: - **`on.roles:`** - Repository access roles that can trigger workflow (array or "all") - Default: `[admin, maintainer, write]` - Available roles: `admin`, `maintainer`, `write`, `read`, `all` - - **Note**: The top-level `roles:` field is deprecated. Use `on.roles:` instead. Run `gh aw fix --write` to migrate. - **`bots:`** - Bot identifiers allowed to trigger workflow regardless of role permissions (array) - Example: `bots: [dependabot[bot], renovate[bot], github-actions[bot]]` - Bot must be active (installed) on repository to trigger workflow @@ -941,7 +940,7 @@ The YAML frontmatter supports these fields: target-repo: "owner/repo" # Optional: cross-repository ``` - Requires PAT as `COPILOT_GITHUB_TOKEN`. Note: `create-agent-task` is deprecated (use `create-agent-session`). + Requires PAT as `COPILOT_GITHUB_TOKEN`. - `assign-to-agent:` - Assign Copilot coding agent to issues ```yaml @@ -1319,7 +1318,7 @@ The YAML frontmatter supports these fields: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` -- **`slash_command:`** - Command trigger configuration for /mention workflows (replaces deprecated `command:`) +- **`slash_command:`** - Command trigger configuration for /mention workflows - **`cache:`** - Cache configuration for workflow dependencies (object or array) - **`cache-memory:`** - Memory MCP server with persistent cache storage (boolean or object) - **`repo-memory:`** - Repository-specific memory storage (boolean) @@ -1589,8 +1588,6 @@ on: name: my-bot # Responds to /my-bot in issues/comments ``` -**Note**: The `command:` trigger field is deprecated. Use `slash_command:` instead. The old syntax still works but may show deprecation warnings. - This automatically creates conditions to match `/my-bot` mentions in issue bodies and comments. You can restrict where commands are active using the `events:` field: @@ -1987,103 +1984,6 @@ safe-outputs: - **Permission Management**: Safe-outputs jobs automatically receive required permissions - **Audit Trail**: Clear separation between AI processing and GitHub API interactions -### Direct Issue Management Pattern (Not Recommended) - -```yaml -permissions: - contents: read - issues: write # Avoid when possible - use safe-outputs instead -``` - -**Note**: Direct write permissions should only be used when safe-outputs cannot meet your workflow requirements. Always prefer the Output Processing Pattern with `safe-outputs` configuration. - -## Output Processing Examples - -### Automatic GitHub Issue Creation - -Use the `safe-outputs.create-issue` configuration to automatically create GitHub issues from coding agent output: - -```aw ---- -on: push -permissions: - contents: read # Main job only needs minimal permissions - actions: read -safe-outputs: - create-issue: - title-prefix: "[analysis] " - labels: [automation, ai-generated] ---- - -# Code Analysis Agent - -Analyze the latest code changes and provide insights. -Create an issue with your final analysis. -``` - -**Key Benefits:** - -- **Permission Separation**: The main job doesn't need `issues: write` permission -- **Automatic Processing**: AI output is automatically parsed and converted to GitHub issues -- **Job Dependencies**: Issue creation only happens after the coding agent completes successfully -- **Output Variables**: The safe-outputs job emits named step outputs for the first successful result of each type: - - `create-issue` → `created_issue_number`, `created_issue_url` - - `create-pull-request` → `created_pr_number`, `created_pr_url` - - `add-comment` → `comment_id`, `comment_url` - - `push-to-pull-request-branch` → `push_commit_sha`, `push_commit_url` - -### Automatic Pull Request Creation - -Use the `safe-outputs.create-pull-request` configuration to automatically create pull requests from coding agent output: - -```aw ---- -on: push -permissions: - actions: read # Main job only needs minimal permissions -safe-outputs: - create-pull-request: - title-prefix: "[bot] " - labels: [automation, ai-generated] - draft: false # Create non-draft PR for immediate review ---- - -# Code Improvement Agent - -Analyze the latest code and suggest improvements. -Create a pull request with your changes. -``` - -**Key Features:** - -- **Secure Branch Naming**: Uses cryptographic random hex instead of user-provided titles -- **Git CLI Integration**: Leverages git CLI commands for branch creation and patch application -- **Environment-based Configuration**: Resolves base branch from GitHub Action context -- **Fail-Fast Error Handling**: Validates required environment variables and patch file existence - -### Automatic Comment Creation - -Use the `safe-outputs.add-comment` configuration to automatically create an issue or pull request comment from coding agent output: - -```aw ---- -on: - issues: - types: [opened] -permissions: - contents: read # Main job only needs minimal permissions - actions: read -safe-outputs: - add-comment: - max: 3 # Optional: create multiple comments (default: 1) ---- - -# Issue Analysis Agent - -Analyze the issue and provide feedback. -Add a comment to the issue with your analysis. -``` - ## Common Workflow Patterns ### Issue Triage Bot @@ -2103,10 +2003,6 @@ safe-outputs: allowed: [bug, enhancement, question, documentation] add-comment: -tools: - github: - min-integrity: none # allow read-only access to issue content for triage analysis - timeout-minutes: 5 --- diff --git a/.github/aw/memory.md b/.github/aw/memory.md index 3defe9b17ff..adea8bc5bbb 100644 --- a/.github/aw/memory.md +++ b/.github/aw/memory.md @@ -156,15 +156,15 @@ tools: allowed-extensions: [".json", ".md"] max-file-size: 10240 # bytes max-file-count: 100 -permissions: - contents: write # Required: repo-memory writes to the repo ``` +The compiler automatically creates a separate `push_repo_memory` job with `contents: write` permission. The main agent job retains read-only permissions. + ### Tradeoffs | ✅ Pros | ❌ Cons | |---|---| -| Persists indefinitely (no expiry) | Requires `contents: write` permission | +| Persists indefinitely (no expiry) | Produces Git commits — repository noise | | Auditable: Git history shows every change | Produces Git commits — repository noise | | Survives cache invalidation | Slower: requires Git clone + push | | Human-readable via GitHub branch UI | Not available for Copilot engine (requires GitHub tools) | @@ -189,17 +189,17 @@ tools: repo-memory: wiki: true allowed-extensions: [".md"] -permissions: - contents: write # Required: wiki writes via push ``` +The compiler automatically creates a separate `push_repo_memory` job with `contents: write` permission. The main agent job retains read-only permissions. + Files follow GitHub Wiki Markdown conventions: use `[[Page Name]]` syntax for internal links, name files with hyphens instead of spaces. ### Tradeoffs | ✅ Pros | ❌ Cons | |---|---| -| Browsable in the GitHub Wiki UI | Requires `contents: write` permission | +| Browsable in the GitHub Wiki UI | Produces Git commits to wiki repo | | Great for human-readable knowledge bases | Produces Git commits to wiki repo | | Standard Markdown with wiki link syntax | Restricted to `.md` files in practice | | Separate from main repo history | Less suitable for structured JSON state | @@ -213,7 +213,7 @@ Files follow GitHub Wiki Markdown conventions: use `[[Page Name]]` syntax for in | **First choice** | ✅ Yes | No | No | | **Storage backend** | GitHub Actions cache | Git branch | GitHub Wiki | | **Persistence** | Up to 90 days | Indefinite | Indefinite | -| **Requires `contents: write`** | No | Yes | Yes | +| **Compiler adds `contents: write`** | No | Yes (push job) | Yes (push job) | | **Repository noise** | None | Git commits | Wiki commits | | **Human-readable in GitHub** | No | Via branch UI | Via Wiki UI | | **Structured data (JSON)** | ✅ Ideal | Possible | Not recommended | diff --git a/.github/aw/test-coverage.md b/.github/aw/test-coverage.md index 19e476897c1..35bd73c2a5e 100644 --- a/.github/aw/test-coverage.md +++ b/.github/aw/test-coverage.md @@ -31,7 +31,6 @@ on: pull_request: types: [opened, synchronize] permissions: - pull-requests: write # post coverage comment actions: read # download artifacts network: defaults tools: