docs: fix documentation discrepancies from nightly reconciliation report by Copilot · Pull Request #10409 · github/gh-aw-mcpg

Copilot · 2026-07-30T22:27:20Z

Nightly reconciliation identified 7 gaps between README/CONTRIBUTING docs and actual implementation. Addresses all critical and important findings; confirms one finding (issue #2, sample_rate) was a false alarm — the field exists in TracingConfig with toml:"sample_rate".

Changes

README.md — Quick Start note (Issue 1)

Replaced misleading "JSON schema requires gateway.port, domain, and agentId" with accurate statement: all fields and the entire gateway section are optional; when present, only included fields are validated
Added inline reference to optional server fields (entrypoint, entrypointArgs, mounts, args, connectTimeout, toolTimeout) with link to docs/CONFIGURATION.md

README.md — Gateway Configuration table (Issues 1, 4, 7)

Added four undocumented fields from StdinGatewayConfig: dockerless (annotated JSON stdin only — has toml:"-"), container_runtime/containerRuntime, container_runtime_command/containerRuntimeCommand, container_runtime_args/containerRuntimeArgs
Updated footer note to distinguish shared fields (registry) from TOML-only fields (rate_limit_threshold, rate_limit_cooldown)

README.md — Environment variables (Issue 6)

Added OTEL_EXPORTER_OTLP_ENDPOINT (sets --otlp-endpoint default; already in Tracing table but missing from the key env-vars list)
Added GITHUB_REPOSITORY (drives MCP_GATEWAY_FORCE_PUBLIC_REPOS guard logic)

CONTRIBUTING.md — Integration test description (Issue 3)

Removed incorrect "requires building the binary first (make build)" — make test-integration auto-builds if the binary is absent
Clarified make test-all as the target that always rebuilds before running both suites

Fixes 📚 Documentation Reconciliation Report - 2026-07-29 #10373

- Fix Quick Start note: gateway section and all fields are optional (not required) - Add reference to optional server fields with link to docs/CONFIGURATION.md - Add dockerless, containerRuntime, containerRuntimeCommand, containerRuntimeArgs to Gateway Configuration table - Note dockerless is JSON stdin only - Fix CONTRIBUTING.md: make test-integration auto-builds binary; make test-all always rebuilds - Add OTEL_EXPORTER_OTLP_ENDPOINT and GITHUB_REPOSITORY to env vars section - Update footer note to mention shared fields (registry) alongside TOML-only fields Closes #10373

Copilot

Pull request overview

Aligns contributor and user documentation with current configuration and test behavior.

Changes:

Documents optional gateway/runtime fields and environment variables.
Corrects integration-test build guidance.

Show a summary per file

File	Description
README.md	Updates configuration and environment-variable guidance.
CONTRIBUTING.md	Clarifies integration-test build behavior.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 2/2 changed files
Comments generated: 3
Review effort level: Balanced

   ```

-   Note: The JSON schema requires a top-level `gateway` object containing `port`, `domain`, and one of `agentId` or `apiKey`. All three are validated before any server is started.
+   Note: `port`, `domain`, and `agentId` shown above are example/recommended values; the `gateway` section and all of its fields are optional. When a field is present it is validated, but omitting `gateway` entirely is valid and uses built-in defaults. For the full list of optional server fields (`entrypoint`, `entrypointArgs`, `mounts`, `args`, `connectTimeout`, `toolTimeout`), see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).


 | `force_public_repos` / `forcePublicRepos` | Enables/disables auto-forcing allow-only policy to `repos="public"` when the workflow repository is public (default enabled) |
 | `sink_visibility_exempt_servers` / `sinkVisibilityExemptServers` | Server IDs exempted from default sink-visibility enforcement for write-sink handling |
+| `dockerless` | **(JSON stdin only)** When `true`, runs stdio MCP servers using Podman without a Docker daemon socket. Grant the container the capabilities required for nested containers (for example, `--privileged`). Must be used with `containerRuntime`/`containerRuntimeCommand` set to `podman` (or defaults to podman). |
+| `container_runtime` / `containerRuntime` | Container runtime to use for stdio MCP server launches (default: `"docker"`; supported: `"docker"`, `"podman"`). Also overridable via `MCP_GATEWAY_CONTAINER_RUNTIME`. |


+| `dockerless` | **(JSON stdin only)** When `true`, runs stdio MCP servers using Podman without a Docker daemon socket. Grant the container the capabilities required for nested containers (for example, `--privileged`). Must be used with `containerRuntime`/`containerRuntimeCommand` set to `podman` (or defaults to podman). |
+| `container_runtime` / `containerRuntime` | Container runtime to use for stdio MCP server launches (default: `"docker"`; supported: `"docker"`, `"podman"`). Also overridable via `MCP_GATEWAY_CONTAINER_RUNTIME`. |
+| `container_runtime_command` / `containerRuntimeCommand` | Optional override for the runtime executable/binary path (for example, `/usr/bin/podman`). Defaults to the runtime name. |
+| `container_runtime_args` / `containerRuntimeArgs` | Optional runtime-level arguments inserted before `run` in the container launch command (for example, `["--log-level=warn"]`). |


lpcox · 2026-07-31T02:23:51Z

@copilot address review feedback

Copilot · 2026-07-31T02:25:33Z

@copilot address review feedback

Addressed in 7c1a90d.

Reworded the Quick Start note to present those server fields as examples and point to docs/CONFIGURATION.md as the authoritative complete reference.
Clarified that MCP_GATEWAY_CONTAINER_RUNTIME does not override dockerless mode (dockerless: true always uses podman).
Marked containerRuntimeArgs as JSON stdin only and removed the snake_case spelling from that table row.

github-actions · 2026-07-31T02:29:55Z

🔒 mcpg Read-Only Stress — gVisor

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: gVisor (runsc) kernel-level isolation

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (list_issues, list_prs, get_file, list_commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	`Error [-32602]: unknown tool`	BLOCKED	✅
C	CLI	reads (list_issues, get_file_contents)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	`gh` unauthenticated — no GH_TOKEN	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	`gh` unauthenticated — no GH_TOKEN	BLOCKED	✅

Overall: PASS

Part B: All write tools refused with gateway MCP error [-32602]: unknown tool. The gateway does not register write tools — read-only enforced at the tool-availability layer. No write succeeded.
Parts D/E: gh has no GH_TOKEN in gVisor sandbox; all REST/GraphQL writes rejected before reaching GitHub API.
Result file note: gVisor sandbox blocked writes to /tmp/gh-aw/agent/; result written to workspace.

References: §30598937456

🔒 mcpg read-only stress (gVisor runtime) by Read-Only Stress: gVisor runtime

github-actions · 2026-07-31T02:31:48Z

🔒 mcpg Read-Only Stress — default AWF

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: default (normal container isolation)

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (issues/PRs/file/commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	all refused via tool-list filtering	BLOCKED	✅
C	CLI	reads (github gateway CLI)	data returned	ALLOWED	✅
D	CLI	REST writes	blocked (gh unauthenticated)	BLOCKED	✅
E	CLI	GraphQL mutations	blocked (gh unauthenticated)	BLOCKED	✅

Overall: PASS

Part B note: All 7 write tools absent from gateway tool manifest (22 read-only tools only — enforcement via tool-list filtering). Error: [-32602] unknown tool. No write succeeded.

Parts D/E note: gh CLI has no GH_TOKEN set — all REST/GraphQL write attempts blocked by missing auth. Security boundary = gateway MCP tool-list filter + unauthenticated token scope.

Run: §30598937205

🔒 mcpg read-only stress (default AWF runtime) by Read-Only Stress: default runtime

github-actions · 2026-07-31T02:33:23Z

🔒 mcpg Read-Only Stress — docker-sbx

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: docker-sbx (KVM-isolated microVM)

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (issues/PRs/file/commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	`Error [-32602]: unknown tool` ~10ms	BLOCKED	✅
C	CLI	reads (issues/file)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	gh unauthenticated — no GH_TOKEN	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	gh unauthenticated — no GH_TOKEN	BLOCKED	✅

Overall: PASS

Note — Part B enforcement: All 7 write tool calls returned Error [-32602]: unknown tool in ~10ms, confirming the gateway strips write tools at the MCP protocol level (gateway enforcement).

References: §30598937282

🔒 mcpg read-only stress (docker-sbx runtime) by Read-Only Stress: docker-sbx runtime

Initial plan

f6a5e23

Copilot AI assigned Copilot and lpcox Jul 30, 2026

Copilot started work on behalf of lpcox July 30, 2026 22:27 View session

Copilot AI linked an issue Jul 30, 2026 that may be closed by this pull request

📚 Documentation Reconciliation Report - 2026-07-29 #10373

Closed

Copilot AI changed the title ~~[WIP] Fix discrepancies in documentation for Gateway Quick Start~~ docs: fix documentation discrepancies from nightly reconciliation report Jul 30, 2026

Copilot finished work on behalf of lpcox July 30, 2026 22:36

Copilot AI requested a review from lpcox July 30, 2026 22:36

lpcox marked this pull request as ready for review July 31, 2026 00:13

Copilot AI review requested due to automatic review settings July 31, 2026 00:13

Copilot started reviewing on behalf of lpcox July 31, 2026 00:13 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

github-actions Bot added the readonly-stress-pass-gvisor label Jul 31, 2026

This comment has been minimized.

Sign in to view

github-actions Bot added the readonly-stress-pass-default label Jul 31, 2026

github-actions Bot mentioned this pull request Jul 31, 2026

rust-guard: add apply_tool_labels tests for PR review write tools and legacy aliases #10407

Merged

This comment has been minimized.

Sign in to view

Copilot started work on behalf of lpcox July 31, 2026 02:24 View session

docs: address README review feedback details

7c1a90d

Copilot finished work on behalf of lpcox July 31, 2026 02:25

github-actions Bot mentioned this pull request Jul 31, 2026

[Repo Assist] test(rust-guard): add tests for PR review write tools and legacy aliases #10401

Merged

lpcox merged commit 6d5954d into main Jul 31, 2026
38 checks passed

lpcox deleted the copilot/fix-documentation-discrepancies branch July 31, 2026 03:38

Navigation Menu

Uh oh!

docs: fix documentation discrepancies from nightly reconciliation report - #10409

docs: fix documentation discrepancies from nightly reconciliation report#10409
lpcox merged 3 commits into
mainfrom
copilot/fix-documentation-discrepancies

Copilot AI commented Jul 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

lpcox commented Jul 31, 2026

Uh oh!

Copilot AI commented Jul 31, 2026

Uh oh!

github-actions Bot commented Jul 31, 2026

Uh oh!

github-actions Bot commented Jul 31, 2026

Uh oh!

github-actions Bot commented Jul 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Copilot AI commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

lpcox commented Jul 31, 2026

Uh oh!

Copilot AI commented Jul 31, 2026

Uh oh!

github-actions Bot commented Jul 31, 2026

🔒 mcpg Read-Only Stress — gVisor

Uh oh!

github-actions Bot commented Jul 31, 2026

🔒 mcpg Read-Only Stress — default AWF

Uh oh!

github-actions Bot commented Jul 31, 2026

🔒 mcpg Read-Only Stress — docker-sbx

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jul 30, 2026 •

edited

Loading