Skip to content

[docs] Self-healing documentation fixes: document tools.github.mode gh-proxy - 2026-04-22 #27839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Apr 22, 2026
+19 −3
Merged

[docs] Self-healing documentation fixes: document tools.github.mode gh-proxy - 2026-04-22 #27839

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions docs/src/content/docs/reference/github-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section heading was renamed to “GitHub Tools Access Modes”, but later in this page there’s still a link to #github-tools-remote-mode (under “Additional Authentication…”). That anchor will no longer exist; update the link/label to point at the new #github-tools-access-modes section (or restore a matching heading ID).

Suggested change
<a id="github-tools-remote-mode"></a>

Copilot uses AI. Check for mistakes.
## 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 |
Comment on lines +99 to +103
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text says only three tools.github.mode values are supported, but the code also accepts the legacy alias cli for gh-proxy (see pkg/workflow/mcp_github_config.go, which maps cli -> gh-proxy). Please document cli as a deprecated alias (e.g., in the table or in the gh-proxy section) so existing workflows are covered.

Copilot uses AI. Check for mistakes.
| `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.
Expand Down
Loading