From 5f5dd3b1cb1eb79693034bfd18c6fb584c209ea4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 10 Nov 2025 22:11:50 +0000 Subject: [PATCH 1/2] docs: Remove bloat from permissions.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Condensed documentation while preserving all essential information: - Consolidated large permission scopes table into concise prose - Merged repetitive configuration sections into shorthand options - Unified common patterns section with inline examples - Streamlined safe outputs and validation sections Result: 206 → 98 lines (52% reduction) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../src/content/docs/reference/permissions.md | 131 ++---------------- 1 file changed, 12 insertions(+), 119 deletions(-) diff --git a/docs/src/content/docs/reference/permissions.md b/docs/src/content/docs/reference/permissions.md index e5660cede49..2af9aad235f 100644 --- a/docs/src/content/docs/reference/permissions.md +++ b/docs/src/content/docs/reference/permissions.md @@ -28,22 +28,7 @@ This model prevents AI agents from accidentally or maliciously modifying reposit ### Permission Scopes -GitHub Actions permissions control access to different GitHub resources: - -| Permission | Read Access | Write Access | -|------------|-------------|--------------| -| `contents` | Read repository code | Push code, create releases | -| `issues` | Read issues | Create/edit issues, add comments | -| `pull-requests` | Read pull requests | Create/edit PRs, add reviews | -| `discussions` | Read discussions | Create/edit discussions | -| `actions` | Read workflow runs | Cancel runs, approve deployments | -| `checks` | Read check runs | Create status checks | -| `deployments` | Read deployments | Create deployments | -| `packages` | Read packages | Publish packages | -| `pages` | Read Pages settings | Deploy to GitHub Pages | -| `statuses` | Read commit statuses | Create commit statuses | - -See [GitHub's permissions reference](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) for the complete list. +Key permissions include `contents` (code access), `issues` (issue management), `pull-requests` (PR management), `discussions`, `actions` (workflow control), `checks`, `deployments`, `packages`, `pages`, and `statuses`. Each has read and write levels. See [GitHub's permissions reference](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) for the complete list. ## Configuration @@ -57,145 +42,53 @@ permissions: issues: write ``` -### Read-All Permissions +### Shorthand Options -Grant read access to all scopes: - -```yaml wrap -permissions: read-all -``` - -Equivalent to setting all permissions to `read`. This is useful for workflows that need to inspect various repository data without making changes. - -### Write-All Permissions (Not Recommended) - -:::caution -Avoid `write-all` in agentic workflows. Use specific permissions with safe outputs instead. -::: - -```yaml wrap -permissions: write-all -``` - -This grants write access to all scopes and should only be used when absolutely necessary, such as for administrative automation tasks with strict access controls. - -### No Permissions - -Disable all permissions: - -```yaml wrap -permissions: {} -``` - -Useful for workflows that only perform computation without accessing GitHub APIs. +- **`read-all`**: Read access to all scopes (useful for inspection workflows) +- **`write-all`**: Write access to all scopes (avoid in agentic workflows; use specific permissions with safe outputs) +- **`{}`**: No permissions (for computation-only workflows) ## Common Patterns -### IssueOps Workflow - -Read repository content, write to issues: +Most workflows follow a similar pattern: read-only permissions for the AI job, with write operations handled through safe outputs: ```yaml wrap -on: - issues: - types: [opened] +# IssueOps: Read code, write to issues permissions: contents: read issues: write safe-outputs: add-comment: max: 5 -``` - -The main AI job runs with `contents: read`. Comment creation happens in a separate safe output job with `issues: write`, ensuring AI-generated content is sanitized before posting. - -### PR Review Workflow -Read pull requests, add review comments: - -```yaml wrap -on: - pull_request: - types: [opened, synchronize] +# PR Review: Read code, write to PRs permissions: contents: read pull-requests: write safe-outputs: create-pr-review-comment: max: 10 -``` -### Scheduled Analysis - -Read-only analysis that creates issues: - -```yaml wrap -on: - schedule: - - cron: "0 9 * * 1" +# Scheduled: Analysis with issue creation permissions: contents: read issues: write safe-outputs: create-issue: max: 3 -``` - -### Manual Workflow - -Maximum permissions for administrative tasks: -```yaml wrap -on: - workflow_dispatch: +# Manual: Admin tasks with approval gate permissions: read-all manual-approval: production ``` -Uses manual approval gate for human oversight before execution. - ## Safe Outputs -Write operations should use safe outputs rather than direct API access: - -```yaml wrap -permissions: - contents: read # AI job runs read-only -safe-outputs: - add-comment: - max: 5 # Separate job with issues: write - create-issue: - max: 3 # Separate job with issues: write -``` - -**Benefits:** -- Content sanitization (removes unsafe content, @mentions) -- Rate limiting (max outputs per run) -- Audit trail (outputs shown in step summary) -- Security isolation (write permissions separated from AI execution) - -See [Safe Outputs](/gh-aw/reference/safe-outputs/) for complete documentation. +Write operations use safe outputs instead of direct API access. This provides content sanitization, rate limiting, audit trails, and security isolation by separating write permissions from AI execution. See [Safe Outputs](/gh-aw/reference/safe-outputs/) for details. ## Permission Validation -The compiler validates permissions during compilation: - -```bash -gh aw compile workflow.md -``` - -**Common validation errors:** -- Undefined permissions (use explicit permission levels) -- Write permissions without safe outputs (security risk) -- Insufficient permissions for declared tools - -Use `--strict` mode for additional permission validation: - -```bash -gh aw compile --strict workflow.md -``` - -Strict mode refuses write permissions and requires explicit network configuration for all operations. +Run `gh aw compile workflow.md` to validate permissions. Common errors include undefined permissions, write permissions without safe outputs, and insufficient permissions for declared tools. Use `--strict` mode to refuse write permissions and require explicit network configuration. ## Related Documentation From c4e342e1073d364558b94c8f21f81dd25c4d8ef1 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 10 Nov 2025 16:30:17 -0800 Subject: [PATCH 2/2] docs: Remove write permissions from all examples, use safe-outputs pattern (#3576) --- .../schema-consistency-checker.lock.yml | 5 ++- .../src/content/docs/reference/permissions.md | 35 +++++++++++-------- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/.github/workflows/schema-consistency-checker.lock.yml b/.github/workflows/schema-consistency-checker.lock.yml index 3fd00408d4a..7cce7a2ed2b 100644 --- a/.github/workflows/schema-consistency-checker.lock.yml +++ b/.github/workflows/schema-consistency-checker.lock.yml @@ -1339,7 +1339,10 @@ jobs: - `pkg/workflow/safe_outputs.go` - safe-outputs configuration - `pkg/workflow/cache.go` - cache and cache-memory configuration - `pkg/workflow/permissions.go` - permissions processing - - `pkg/workflow/network.go` - network permissions + - `pkg/workflow/engine.go` - engine config and network permissions types + - `pkg/workflow/domains.go` - network domain allowlist functions + - `pkg/workflow/engine_network_hooks.go` - network hook generation + - `pkg/workflow/engine_firewall_support.go` - firewall support checking - `pkg/workflow/strict_mode.go` - strict mode validation - `pkg/workflow/stop_after.go` - stop-after processing - `pkg/workflow/safe_jobs.go` - safe-jobs configuration diff --git a/docs/src/content/docs/reference/permissions.md b/docs/src/content/docs/reference/permissions.md index 2af9aad235f..417123430eb 100644 --- a/docs/src/content/docs/reference/permissions.md +++ b/docs/src/content/docs/reference/permissions.md @@ -10,8 +10,10 @@ The `permissions:` section controls what GitHub API operations your workflow can ```yaml wrap permissions: contents: read - issues: write - pull-requests: write + actions: read +safe-outputs: + create-issue: + add-comment: ``` ## Permission Model @@ -20,9 +22,9 @@ permissions: Agentic workflows follow a principle of least privilege: -- **Read-only by default**: Workflows run with minimal permissions +- **Read-only by default**: Main job runs with minimal read permissions only - **Write through safe outputs**: Write operations happen in separate jobs with sanitized content -- **Explicit permissions**: All permissions must be declared in frontmatter +- **No direct write permissions**: Use safe-outputs instead of `write` permissions in the main job This model prevents AI agents from accidentally or maliciously modifying repository content during execution. @@ -39,40 +41,45 @@ Specify individual permission levels: ```yaml wrap permissions: contents: read - issues: write + actions: read +safe-outputs: + create-issue: ``` ### Shorthand Options - **`read-all`**: Read access to all scopes (useful for inspection workflows) -- **`write-all`**: Write access to all scopes (avoid in agentic workflows; use specific permissions with safe outputs) - **`{}`**: No permissions (for computation-only workflows) +:::caution +Avoid using `write-all` or direct write permissions in agentic workflows. Use [safe outputs](/gh-aw/reference/safe-outputs/) instead for secure write operations. +::: + ## Common Patterns -Most workflows follow a similar pattern: read-only permissions for the AI job, with write operations handled through safe outputs: +All workflows should use read-only permissions with safe outputs for write operations: ```yaml wrap -# IssueOps: Read code, write to issues +# IssueOps: Read code, comment via safe outputs permissions: contents: read - issues: write + actions: read safe-outputs: add-comment: max: 5 -# PR Review: Read code, write to PRs +# PR Review: Read code, review via safe outputs permissions: contents: read - pull-requests: write + actions: read safe-outputs: create-pr-review-comment: max: 10 -# Scheduled: Analysis with issue creation +# Scheduled: Analysis with issue creation via safe outputs permissions: contents: read - issues: write + actions: read safe-outputs: create-issue: max: 3 @@ -88,7 +95,7 @@ Write operations use safe outputs instead of direct API access. This provides co ## Permission Validation -Run `gh aw compile workflow.md` to validate permissions. Common errors include undefined permissions, write permissions without safe outputs, and insufficient permissions for declared tools. Use `--strict` mode to refuse write permissions and require explicit network configuration. +Run `gh aw compile workflow.md` to validate permissions. Common errors include undefined permissions, direct write permissions in the main job (use safe outputs instead), and insufficient permissions for declared tools. Use `--strict` mode to enforce read-only permissions and require explicit network configuration. ## Related Documentation