diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index 784cce70e0d..2b27b0e1812 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -411,17 +411,17 @@ Ensure discussions are enabled (**Settings → Features → Discussions**) and t Use `fallback-to-issue: true` (the default) to automatically create an issue if discussions aren't available. See [Discussion Creation](/gh-aw/reference/safe-outputs/#discussion-creation-create-discussion) for details. -### How do I turn off discussions in add-comment? +### How do I enable discussions in add-comment? -By default, `add-comment` requests `discussions: write`. If your GitHub App lacks Discussions (causing 422 errors), set `discussions: false` to drop only the permission — discussion targeting itself remains automatic: +By default, `add-comment` does not request `discussions: write` — the permission is opt-in. To comment on discussions, set `discussions: true`: ```yaml wrap safe-outputs: add-comment: - discussions: false + discussions: true ``` -Similarly, opt out of `issues: write` or `pull-requests: write` with `issues: false` or `pull-requests: false`. +`issues: write` and `pull-requests: write` are requested by default; opt out per-permission with `issues: false` or `pull-requests: false`. ### Why is my create-pull-request workflow failing with "GitHub Actions is not permitted to create or approve pull requests"? diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 67b73a4138f..7ec695aa2bd 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -294,7 +294,7 @@ safe-outputs: add-comment: max: 3 # max comments (default: 1) target: "*" # "triggering" (default), "*", or number - discussions: false # exclude discussions:write permission (default: true) + discussions: true # request discussions:write permission (default: false) target-repo: "owner/repo" # cross-repository allowed-repos: ["org/repo1", "org/repo2"] # additional allowed repositories hide-older-comments: true # hide previous comments from same workflow diff --git a/docs/src/content/docs/specs/safe-outputs-specification.md b/docs/src/content/docs/specs/safe-outputs-specification.md index 6724cd4dcf6..2fa4a8b4b27 100644 --- a/docs/src/content/docs/specs/safe-outputs-specification.md +++ b/docs/src/content/docs/specs/safe-outputs-specification.md @@ -2140,7 +2140,7 @@ This extension applies to safe-output processor messages for `add_comment` (incl - `max`: Operation limit (default: 1) - `target`: Filter by type ("issue", "pull_request", "discussion", "*"). This configuration field applies to static workflow configuration (`safe-outputs.add-comment.target`) and is distinct from the runtime per-message `target: "status"` extension above. - `hide-older-comments`: Hide previous workflow comments -- `discussions`: Control `discussions:write` permission (default: true) +- `discussions`: Control `discussions:write` permission (default: false). Set to `true` to comment on discussions. - `target-repo`: Cross-repository target - `allowed-repos`: Cross-repo allowlist @@ -2151,21 +2151,21 @@ This extension applies to safe-output processor messages for `add_comment` (incl - `contents: read` - Repository metadata and file access - `issues: write` - Comment creation on issues - `pull-requests: write` - Comment creation on pull requests -- `discussions: write` - Comment creation on discussions (when `discussions: true` or omitted) +- `discussions: write` - Comment creation on discussions (only when `discussions: true`) *GitHub App* (if using `safe-outputs.app` configuration): - `issues: write` - Comment creation on issues - `pull-requests: write` - Comment creation on pull requests -- `discussions: write` - Comment creation on discussions (when `discussions: true` or omitted) +- `discussions: write` - Comment creation on discussions (only when `discussions: true`) - `metadata: read` - Repository metadata (automatically granted) **Permission Control via `discussions` Field**: The optional `discussions` boolean field controls whether `discussions:write` permission is requested: -- **Default behavior** (`discussions: true` or omitted): Includes `discussions:write` permission for maximum compatibility. Use this when the GitHub App has Discussions permission granted. -- **Opt-out** (`discussions: false`): Excludes `discussions:write` permission. Use this when the GitHub App lacks Discussions permission to prevent 422 errors during token generation. +- **Default behavior** (`discussions: false` or omitted): Excludes `discussions:write` permission. This is safe for environments where the GitHub App lacks Discussions permission and avoids 422 errors during token generation. +- **Opt-in** (`discussions: true`): Includes `discussions:write` permission. Use this when the workflow needs to comment on discussions and the GitHub App has Discussions permission granted. **Example Configuration**: @@ -2179,13 +2179,13 @@ safe-outputs: add-comment: target: "*" max: 1 - discussions: false # Exclude discussions:write permission + discussions: true # Opt in to discussions:write permission ``` **Notes**: -- By default, requires write permissions for all three entity types (issues, PRs, discussions) since comments can be added to any type -- When `discussions: false`, the workflow only requests `issues:write` and `pull-requests:write` permissions +- By default, requires write permissions only for `issues` and `pull-requests`; `discussions:write` is opt-in +- Set `discussions: true` to add `discussions:write` and enable commenting on discussions - Discussion-related safe outputs (`create-discussion`, `close-discussion`, `update-discussion`) independently add `discussions:write` permission when configured - Cross-repository commenting requires appropriate permissions in target repository - The `contents: read` permission is always included for repository context access @@ -5151,6 +5151,12 @@ This specification revision aligns with directly relevant `CHANGELOG.md` entries - **Earlier changelog entry**: status comments were decoupled from default AI reaction behavior; explicit `on.status-comment` configuration is required when status comments are desired. - **Earlier changelog entry**: `command` trigger was renamed to `slash_command` with deprecation compatibility. +**Version 1.24.0** (2026-06-13): + +- **Changed**: Default value of the `discussions` field on `add-comment` inverted from `true` to `false`. The `discussions:write` permission is now opt-in. Set `discussions: true` to comment on discussions; omitting the field no longer requests `discussions:write`. The `hide-comment.discussions` default remains `true`. +- **Updated**: Section 7.3 `add_comment` permission documentation, configuration examples, and notes to reflect the opt-in default. +- **Updated**: Publication metadata to 1.24.0. + **Version 1.23.0** (2026-06-10): - **Added**: `create_check_run` safe output type definition in Section 7.3, including full MCP tool schema, operational semantics, configuration parameters, and permission requirements.