From b402e6d32c4b195d906beed9c5230f467ed3f06f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Wed, 22 Apr 2026 13:33:43 +0000
Subject: [PATCH] docs: document tools.github.mode gh-proxy access mode

The tools.github.mode field now accepts three values: local (default),
remote, and gh-proxy. The gh-proxy mode was introduced in #27707 as the
preferred alternative to the legacy features.cli-proxy flag, but was
not yet reflected in the github-tools.md reference page.

Expands the "GitHub Tools Remote Mode" section into "GitHub Tools Access
Modes" with a summary table and prose for each of the three modes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../content/docs/reference/github-tools.md    | 22 ++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/docs/src/content/docs/reference/github-tools.md b/docs/src/content/docs/reference/github-tools.md
index 2e8c19ab0c7..00564cb3088 100644
--- a/docs/src/content/docs/reference/github-tools.md
+++ b/docs/src/content/docs/reference/github-tools.md
@@ -94,17 +94,33 @@ The `repos` field was renamed to `allowed-repos` to better reflect its purpose.
 
 By default, the GitHub Tools can read from the current repository and all public repositories (if permitted by the network firewall). To read from other private repositories, you must configure additional authentication. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for details and examples.
 
-## GitHub Tools Remote Mode
+## GitHub Tools Access Modes
 
-By default the GitHub Tools run in "local mode", where the GitHub MCP Server runs within the GitHub Actions VM hosting your agentic workflow. You can switch to "remote mode", which uses a hosted MCP server managed by GitHub. Remote mode requires [additional authentication](#additional-authentication-for-github-tools) and enables additional filtering and capabilities.
+The `tools.github.mode` field controls how the agent accesses GitHub. Three values are supported:
+
+| Mode | Transport | Notes |
+|------|-----------|-------|
+| `local` (default) | Docker-based GitHub MCP Server inside the Actions VM | No extra authentication required |
+| `remote` | Hosted GitHub MCP Server managed by GitHub | Requires [additional authentication](#additional-authentication-for-github-tools) |
+| `gh-proxy` | Pre-authenticated `gh` CLI directly (no MCP server) | Preferred for performance; required for [integrity reactions](/gh-aw/reference/integrity/) |
+
+**`remote` mode** — uses a hosted MCP server managed by GitHub. Requires a GitHub token with appropriate permissions:
 
 ```yaml wrap
 tools:
   github:
-    mode: remote  # Default: "local" (Docker)
+    mode: remote
     github-token: ${{ secrets.CUSTOM_PAT }}  # Required for remote mode
 ```
 
+**`gh-proxy` mode** — uses the pre-authenticated `gh` CLI directly instead of an MCP server. This offers lower latency because there is no MCP server startup overhead, and it is required for workflows that use [integrity reactions](/gh-aw/reference/integrity/). The legacy `features: {cli-proxy: true}` feature flag is equivalent and is still accepted for backward compatibility.
+
+```yaml wrap
+tools:
+  github:
+    mode: gh-proxy
+```
+
 ## Additional Authentication for GitHub Tools
 
 In some circumstances you must use a GitHub PAT or GitHub app to give the GitHub tools used by your workflow additional capabilities.