diff --git a/docs/src/content/docs/reference/safe-outputs-pull-requests.md b/docs/src/content/docs/reference/safe-outputs-pull-requests.md index 046f9b7f142..403cd7f3a16 100644 --- a/docs/src/content/docs/reference/safe-outputs-pull-requests.md +++ b/docs/src/content/docs/reference/safe-outputs-pull-requests.md @@ -415,7 +415,8 @@ The `protected-files` field accepts either a string policy value or an object wi | Value | Behavior | |-------|-----------| -| `blocked` (default) | Hard-block: the safe output fails with an error | +| `request_review` (default) | Create the pull request and submit a `REQUEST_CHANGES` review listing the protected files. The agent's work is preserved, and a human reviewer must approve before merge. | +| `blocked` | Hard-block: the safe output fails with an error | | `fallback-to-issue` | Create a review issue with instructions for the human to apply or reject the changes manually | | `allowed` | No restriction — all protected file changes are permitted. **Use only when the workflow is explicitly designed to manage these files.** | @@ -425,7 +426,7 @@ The `protected-files` field accepts either a string policy value or an object wi safe-outputs: create-pull-request: protected-files: - policy: fallback-to-issue # same values as string form (default: blocked) + policy: fallback-to-issue # same values as string form (default: request_review) exclude: - AGENTS.md # allow the agent to update its own instruction file - CHANGELOG.md # allow the agent to update the changelog @@ -475,7 +476,7 @@ on: type: string default: fallback-to-issue description: > - Protected-file policy: 'blocked', 'fallback-to-issue', or 'allowed'. + Protected-file policy: 'request_review', 'blocked', 'fallback-to-issue', or 'allowed'. patch-format: type: string default: bundle diff --git a/docs/src/content/docs/reference/threat-detection.md b/docs/src/content/docs/reference/threat-detection.md index 65cad60ff8a..b2a53cfc6ee 100644 --- a/docs/src/content/docs/reference/threat-detection.md +++ b/docs/src/content/docs/reference/threat-detection.md @@ -331,6 +331,10 @@ Reasons: If the detection process itself fails (e.g., network issues, tool errors), the workflow stops and safe outputs are not applied. This fail-safe approach prevents potentially malicious content from being processed. +**When Detection Returns a Warning:** + +A warning is a lower-severity signal than a hard threat: the safe output is allowed to proceed, but human review is required before merge. When `create-pull-request` is the safe output, the handler submits a `REQUEST_CHANGES` pull request review whose body includes the detection reason and a link to the workflow run logs. If a `request_review` protected-files gate also fires in the same run, both signals are composed into a single review body separated by a horizontal rule. + ## Supply Chain Protection (Protected Files) Beyond AI-powered threat detection, GitHub Agentic Workflows includes a static, rule-based protection layer that guards against **supply chain attacks** — cases where an AI agent could (intentionally or accidentally) modify files that control how software is built, tested, or deployed. @@ -360,7 +364,8 @@ Configure how each safe output handles protected file changes using the `protect | Value | Behavior | |-------|-----------| -| `blocked` (default) | Hard-block: the safe output fails with an error message | +| `request_review` (default) | Create the pull request and submit a `REQUEST_CHANGES` review listing the protected files. A human reviewer must approve before merge. | +| `blocked` | Hard-block: the safe output fails with an error message | | `allowed` | No restriction — all protected file changes are permitted | | `fallback-to-issue` | Create a review issue instead of a PR / push, so a human can inspect and apply the changes manually |