From f72dc88b87c3e7ee235abc36703ba91c97e6c8b6 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 2 Nov 2025 06:08:52 +0000 Subject: [PATCH] Update documentation for security features from 2025-11-02 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/src/content/docs/guides/security.md | 80 ++++++++++++++++++- .../src/content/docs/reference/frontmatter.md | 10 ++- docs/src/content/docs/reference/triggers.md | 57 +++++++++++++ 3 files changed, 145 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/guides/security.md b/docs/src/content/docs/guides/security.md index a940efa692..ac3bd48a68 100644 --- a/docs/src/content/docs/guides/security.md +++ b/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. diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index aacc7e5d20..bb340147a1 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/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:`) diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md index 9cab951e6b..bb6a307a1a 100644 --- a/docs/src/content/docs/reference/triggers.md +++ b/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