[docs] Update documentation for security features from 2025-11-02

docs/src/content/docs/guides/security.md

@@ -82,6 +82,78 @@ permissions:
   contents: read
 ```
 
+#### Fork Protection for Pull Request Triggers
+
+Pull request workflows block forks by default for security. Workflows triggered by `pull_request` events only execute for pull requests from the same repository unless explicitly configured to allow forks.
+
+**Default behavior (blocks all forks):**
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize]
+# Blocks all forked PRs, only allows same-repo PRs
+```
+
+**Allow specific fork patterns:**
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize]
+    forks: ["trusted-org/*"]  # Allow forks from specific org
+```
+
+**Allow all forks (use with caution):**
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize]
+    forks: ["*"]  # Allow all forks
+```
+
+The compiler generates conditions using repository ID comparison (`github.event.pull_request.head.repo.id == github.repository_id`) for reliable fork detection that is not affected by repository renames.
+
+#### workflow_run Trigger Security
+
+Workflows triggered by `workflow_run` events include automatic protections against cross-repository attacks:
+
+**Automatic repository validation:**
+
+The compiler automatically injects a repository ID check into the activation job for all workflows using `workflow_run` triggers:
+
+```yaml
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+```
+
+This generates a safety condition that prevents execution if the triggering workflow_run is from a different repository:
+
+```yaml
+if: >
+  (user_condition) &&
+  ((github.event_name != 'workflow_run') ||
+   (github.event.workflow_run.repository.id == github.repository_id))
+```
+
+The safety check combines with user-specified conditions using AND logic and protects all downstream jobs through job dependencies.
+
+**Branch restriction validation:**
+
+Workflows with `workflow_run` triggers should include branch restrictions to prevent execution for workflow runs on all branches:
+
+```yaml
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches:
+      - main
+      - develop
+```
+
+Without branch restrictions, workflows emit warnings during compilation (or errors in strict mode). Branch restrictions improve security by limiting which branch workflows can trigger the workflow_run event.
+
 **Production workflows**: Consider using strict mode to enforce additional security constraints:
 
 ```yaml
@@ -101,7 +173,13 @@ Strict mode prevents write permissions (`contents:write`, `issues:write`, `pull-
 
 GitHub Actions workflows are designed to be steps within a larger process. Some critical operations should always involve human review:
 
-- **Approval gates**: Use manual approval steps for high-risk operations like deployments, secret management, or external tool invocations
+- **Approval gates**: Use the `manual-approval` field to require manual approval before workflow execution. Configure environment protection rules in repository settings to specify required reviewers and approval policies:
+  ```yaml
+  on:
+    workflow_dispatch:
+    manual-approval: production
+  ```
+  See [Manual Approval Gates](/gh-aw/reference/triggers/#manual-approval-gates-manual-approval) for configuration details.
 - **Pull requests require humans**: GitHub Actions cannot approve or merge pull requests. This means a human will always be involved in reviewing and merging pull requests that contain agentic workflows.
 - **Plan-apply separation**: Implement a "plan" phase that generates a preview of actions before execution. This allows human reviewers to assess the impact of changes. This is usually done via an output issue or pull request.
 - **Review and audit**: Regularly review workflow history, permissions, and tool usage to ensure compliance with security policies.

docs/src/content/docs/reference/frontmatter.md

@@ -26,7 +26,15 @@ The frontmatter combines standard GitHub Actions properties (`on`, `permissions`
 
 ### Trigger Events (`on:`)
 
-The `on:` section uses standard GitHub Actions syntax to define workflow triggers. See [Trigger Events](/gh-aw/reference/triggers/).
+The `on:` section uses standard GitHub Actions syntax to define workflow triggers, with additional fields for security and approval controls:
+
+- Standard GitHub Actions triggers (push, pull_request, issues, schedule, etc.)
+- `reaction:` - Add emoji reactions to triggering items
+- `stop-after:` - Automatically disable triggers after a deadline
+- `manual-approval:` - Require manual approval using environment protection rules
+- `forks:` - Configure fork filtering for pull_request triggers
+
+See [Trigger Events](/gh-aw/reference/triggers/) for complete documentation.
 
 ### Description (`description:`)
 

docs/src/content/docs/reference/triggers.md

@@ -59,6 +59,25 @@ on:
   reaction: "rocket"
 ```
 
+#### Fork Filtering (`forks:`)
+
+Pull request workflows block forks by default for security. Use the `forks:` field to allow specific fork patterns:
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize]
+    forks: ["trusted-org/*"]  # Allow forks from trusted-org
+```
+
+**Available patterns:**
+- `["*"]` - Allow all forks (use with caution)
+- `["owner/*"]` - Allow forks from specific organization or user
+- `["owner/repo"]` - Allow specific repository
+- Omit `forks` field - Default behavior (same-repository PRs only)
+
+The compiler uses repository ID comparison for reliable fork detection that is not affected by repository renames. See the [Security Guide](/gh-aw/guides/security/#fork-protection-for-pull-request-triggers) for detailed security implications.
+
 ### Comment Triggers
 ```yaml
 on:
@@ -71,6 +90,30 @@ on:
   reaction: "eyes"
 ```
 
+### Workflow Run Triggers (`workflow_run:`)
+
+Trigger workflows after another workflow completes. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run).
+
+```yaml
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches:
+      - main
+      - develop
+```
+
+#### Security Protections
+
+Workflows with `workflow_run` triggers include automatic security protections:
+
+**Automatic repository validation:** The compiler automatically injects a repository ID check to prevent cross-repository attacks. This safety condition ensures workflows only execute when triggered by workflow runs from the same repository.
+
+**Branch restrictions required:** Include `branches` to limit which branch workflows can trigger the event. Without branch restrictions, the compiler emits warnings (or errors in strict mode). This prevents unexpected execution for workflow runs on all branches.
+
+See the [Security Guide](/gh-aw/guides/security/#workflow_run-trigger-security) for detailed security behavior and implementation.
+
 ### Command Triggers (`command:`)
 
 The `command:` trigger creates workflows that respond to `/command-name` mentions in issues, pull requests, and comments. See [Command Triggers](/gh-aw/reference/command-triggers/) for complete documentation.
@@ -172,6 +215,20 @@ on:
 
 Accepts absolute dates (`YYYY-MM-DD`, `MM/DD/YYYY`, `DD/MM/YYYY`, `January 2 2006`, `1st June 2025`, ISO 8601) or relative deltas (`+7d`, `+25h`, `+1d12h30m`) calculated from compilation time. The minimum granularity is hours - minute-only units (e.g., `+30m`) are not allowed. Recompiling the workflow resets the stop time.
 
+### Manual Approval Gates (`manual-approval:`)
+
+Require manual approval before workflow execution using GitHub environment protection rules:
+
+```yaml
+on:
+  workflow_dispatch:
+  manual-approval: production
+```
+
+The `manual-approval` field sets the `environment` on the activation job, enabling manual approval gates configured in repository or organization settings. This provides human-in-the-loop control for sensitive operations.
+
+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.
+
 ## Related Documentation
 
 - [Command Triggers](/gh-aw/reference/command-triggers/) - Special @mention triggers and context text