diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index 20b603d907..d35322c67e 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -484,24 +484,29 @@ These resources contain workflow patterns, best practices, safe outputs, and per - **Always use `safe-outputs` instead** for any GitHub write operations (creating issues, adding comments, etc.) - **Mode configuration** - Both `mode: local` (Docker-based, default) and `mode: remote` (hosted) are supported. Remote mode offers faster startup and no Docker requirement. - **GitHub lockdown Mode (Security Feature)**: - - GitHub lockdown mode is a security feature that filters content in public repositories to only show issues, PRs, and comments from users with push access. This protects workflows from processing potentially malicious input from untrusted users. - - - **Automatic by default** - Lockdown is automatically enabled for public repositories, and has no impact for for private repositories (where all collaborators are trusted) - - **When to disable**: Only disable lockdown (`lockdown: false`) for specific safe use cases: - - Issue triage/labeling workflows with restricted safe outputs - - Spam detection systems designed to handle untrusted content - - Public status dashboards with read-only operations - - Command workflows that explicitly verify user permissions before acting - - **How to disable**: + **Guard Policies (`repos` and `min-integrity`)**: + + Guard policies restrict which repositories and content integrity levels the GitHub MCP server can access during agent execution. These are experimental features that apply fine-grained access control at the MCP gateway level. + + - **`repos`** - Restricts which repositories the agent can access: + - `"all"` — All repositories accessible by the token + - `"public"` — Public repositories only + - Array of patterns — Specific repos or wildcards (e.g., `["myorg/*", "myorg/api-*"]`) + - **`min-integrity`** - Sets the minimum integrity level for content: + - `approved` — Only content from owners, members, and collaborators (highest trust) + - `unapproved` — Include contributors and first-time contributors + - `none` — Include all content regardless of author association + - **Both fields are required** when either is specified (you cannot use one without the other) + - **Automatic protection** - When neither `repos` nor `min-integrity` is configured, public repositories automatically get `min-integrity: approved` applied at runtime + - **Example**: ```yaml tools: github: - lockdown: false # Only for workflows designed to safely process all user input + toolsets: [default] + repos: "all" + min-integrity: approved # Only content from trusted collaborators ``` - - **Security considerations**: Workflows with `lockdown: false` should have read-only operations, restrictive safe outputs with specific allowed values, no bash/web-fetch/playwright tools, and explicit input validation - - **Documentation**: See https://github.github.com/gh-aw/reference/lockdown-mode/ for complete guidance + - **Documentation**: See https://github.github.com/gh-aw/reference/github-tools/#guard-policies for complete guidance **Advanced static analysis tools**: For advanced code analysis tasks, see `.github/aw/serena-tool.md` for when and how to use Serena language server.