Uh oh!
There was an error while loading. Please reload this page.
Document sandbox and GitHub access profiles - #53283
Conversation
Visual Regression Check — Unable to CompleteI attempted to capture screenshots (mobile 375x812, tablet 768x1024, desktop 1440x900) and accessibility snapshots of (host.docker.internal/redacted) for this PR, but every navigation attempt returned HTTP 403 Forbidden from the Playwright browser sandbox, even though the workflow reported the docs server as ready.
No visual diffs or accessibility findings could be produced as a result. This appears to be a network/firewall restriction preventing the browser tool from reaching host.docker.internal:4321. Recommend verifying the Playwright browser egress allowlist permits that host/port. Warning Firewall blocked 6 domainsThe following domains were blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "accounts.google.com"
- "android.clients.google.com"
- "clients2.google.com"
- "host.docker.internal"
- "www.google.com"
- "www.gstatic.com"See Network Configuration for more information.
|
There was a problem hiding this comment.
Pull request overview
Documents canonical sandbox, GitHub access, and MCP exposure profiles across user and workflow-authoring guidance.
Changes:
- Adds security profile references and compatibility matrices.
- Updates runtime, engine, migration, and authoring guidance.
- Aligns examples and release notes with canonical access modes.
Show a summary per file
| File | Description |
|---|---|
docs/src/content/docs/reference/tools.md | Clarifies MCP exposure mode. |
docs/src/content/docs/reference/security-profiles.md | Adds the user-facing profile matrix. |
docs/src/content/docs/reference/sandbox.md | Links runtime compatibility guidance. |
docs/src/content/docs/reference/integrity.md | Documents integrity access constraints. |
docs/src/content/docs/reference/glossary.md | Defines access and exposure modes. |
docs/src/content/docs/reference/github-tools.md | Updates GitHub mode guidance. |
docs/src/content/docs/reference/frontmatter.md | Links profile selection guidance. |
docs/src/content/docs/reference/engines.md | Clarifies Pi tool exposure. |
docs/src/content/docs/reference/agent-runtimes.md | Expands runtime compatibility details. |
docs/src/content/docs/introduction/architecture.mdx | Separates runtime and access concepts. |
docs/src/content/docs/guides/upgrading.md | Adds migration mappings. |
docs/src/content/docs/examples/maintaining-repos.md | Updates integrity terminology. |
docs/src/content/docs/engines/pi.md | Documents derived CLI modes. |
docs/astro.config.mjs | Adds security profiles navigation. |
.github/aw/upgrade-agentic-workflows.md | Updates MCP migration example. |
.github/aw/update-agentic-workflow.md | Adds profile-aware update guidance. |
.github/aw/token-optimization.md | Removes invalid CLI toolsets. |
.github/aw/syntax-tools-imports.md | Documents access and exposure syntax. |
.github/aw/syntax-agentic.md | Updates runtime and integrity constraints. |
.github/aw/subagents.md | Separates MCP wrappers from gh. |
.github/aw/security-profiles.md | Adds canonical agent guidance. |
.github/aw/release-workflow.md | Updates release tool guidance. |
.github/aw/mcp-clis.md | Clarifies MCP CLI semantics. |
.github/aw/github-mcp-server.md | Corrects local MCP behavior. |
.github/aw/github-agentic-workflows.md | Updates workflow defaults. |
.github/aw/designer.md | Prevents CLI/MCP field mixing. |
.github/aw/designer-mappings.md | Refines tool-selection mappings. |
.github/aw/create-agentic-workflow.md | Adds profile-aware creation guidance. |
.github/aw/agent-runtime-instructions.md | Updates runtime provisioning guidance. |
.changeset/patch-document-security-profiles.md | Records documentation changes. |
.changeset/github-access-mode-homogeneous.md | Corrects warning behavior notes. |
Review details
- Files reviewed: 31/31 changed files
- Comments generated: 11
- Review effort level: Balanced
| | --- | --- | --- | | ||
| | `sandbox.agent.runtime` | Agent isolation, AWF privileges, and host/service connectivity | How GitHub APIs are exposed | | ||
| | `tools.github.mode` | GitHub access through the `gh` CLI or a GitHub MCP server | How non-GitHub MCP servers are exposed | | ||
| | `tools.mcp-mode` | Whether MCP servers, including a selected GitHub MCP server, are exposed as native MCP tools or CLI wrappers | GitHub transport or sandbox isolation | |
| ## MCP exposure profile | ||
| `tools.mcp-mode: cli` exposes user-facing MCP servers as CLI wrappers on `PATH`, including the GitHub MCP server when `mcp-local` or `mcp-remote` is selected. It does not select `tools.github.mode: cli` and does not turn the GitHub MCP server into the authenticated `gh` CLI. Leave `tools.mcp-mode` omitted, or set it to `default`, for native MCP exposure. |
| For MCP-capable engines, an omitted mode resolves to `mcp-local` for backward compatibility. New workflows should select `cli` explicitly unless they need GitHub MCP tools. `features.integrity-reactions: true` resolves an omitted mode to `cli`. Engines without native MCP support, including Pi, automatically derive both `tools.github.mode: cli` and `tools.mcp-mode: cli`; do not set an MCP GitHub mode for them. | ||
| The fields `toolsets` and `allowed` configure either GitHub MCP mode; `version` and `args` configure only `mcp-local`. All four are ignored with an explicit `tools.github.mode: cli` and produce a compiler warning. Policy fields such as `allowed-repos`, `min-integrity`, `github-token`, and `github-app` remain meaningful in every GitHub access mode. |
| ### GitHub Access Mode (`tools.github.mode`) | ||
| A `tools.github` field that controls how the agent accesses GitHub APIs. Three canonical values are supported: `cli` (recommended default — pre-authenticated `gh` CLI, no MCP server registered, token never exposed to the agent container; replaces the deprecated `features.cli-proxy: true`), `mcp-local` (Docker-based GitHub MCP server, for workflows that need MCP-only fields), and `mcp-remote` (hosted GitHub MCP server at `api.githubcopilot.com`; requires additional authentication). The legacy values `gh-proxy` (= `cli`), `local` (= `mcp-local`), and `remote` (= `mcp-remote`) are still accepted for backward compatibility and migrated by `gh aw fix`. See [GitHub Tools Reference](/gh-aw/reference/github-tools/). | ||
| A `tools.github` field that selects GitHub API access through the pre-authenticated `gh` CLI (`cli`), a local Docker GitHub MCP server (`mcp-local`), or the hosted GitHub MCP service (`mcp-remote`). This selector is independent from the sandbox runtime and `tools.mcp-mode`. Legacy values are accepted only for migration. See [Security Profile Selection](/gh-aw/reference/security-profiles/) and [GitHub Tools Reference](/gh-aw/reference/github-tools/). |
| Workflows that use GitHub Actions `services:` with published ports remain reachable from the agent sandbox only when `sandbox.agent.runtime: docker-sudo-iptables` is set; recompiling regenerates the `--allow-host-service-ports` value used to reach those services. | ||
| GitHub access values are also normalized: `gh-proxy` becomes `cli`, and `local` or `remote` become `mcp-local` or `mcp-remote`. The removed `features.cli-proxy` flag migrates to `tools.github.mode: cli`, while `tools.cli-proxy` migrates to the distinct `tools.mcp-mode: cli` MCP exposure setting. Review the [security profile matrix](/gh-aw/reference/security-profiles/) before combining migrated fields. |
| For MCP-capable engines, omitted `tools.github.mode` resolves to `mcp-local`. Select `cli` explicitly for new CLI-based workflows. Engines without MCP support, including Pi, automatically derive `tools.github.mode: cli` and `tools.mcp-mode: cli`; do not select an MCP mode for them. | ||
| `toolsets` and `allowed` apply to either GitHub MCP mode; `version` and `args` apply only to `mcp-local`. Do not combine them with explicit `mode: cli`; the compiler ignores them with a warning. `allowed-repos`, `min-integrity`, `github-token`, and `github-app` remain meaningful in all modes. |
| MCP CLI exposes mounted MCP servers as shell commands on `PATH`. Enabled by `tools.mcp-mode: cli`. | ||
| This is an MCP exposure setting, not GitHub access. It can wrap a selected GitHub MCP server but does not provide the authenticated `gh` CLI. Configure `tools.github.mode` separately; see [security-profiles.md](security-profiles.md). |
| - **The `release` job must output `release_id`** — the agent needs the database ID to reference the correct release | ||
| - **Pre-fetch all data in `steps:`** before the agent runs; write compact JSON to `/tmp/gh-aw/agent/release-data/` | ||
| - **Include `tools.mcp-mode: cli`** in the agent `tools:` block to allow `gh` and `jq` use inside the sandbox | ||
| - **Include `tools.github.mode: cli`** for authenticated `gh` access; use `tools.mcp-mode: cli` to expose selected MCP servers as CLI wrappers |
| | --- | --- | | ||
| | `sandbox.agent.runtime` | Agent isolation, AWF privilege, and host/service access | | ||
| | `tools.github.mode` | GitHub access through `gh` or a GitHub MCP server | | ||
| | `tools.mcp-mode` | Native MCP exposure versus CLI wrappers for MCP servers, including a selected GitHub MCP server | |
| - `timeout:` - Per-operation timeout in seconds for all tool and MCP calls (integer or expression, default: 60 s for all engines). | ||
| - `startup-timeout:` - Timeout in seconds for MCP server initialization (integer or expression, default: 120). | ||
| - `mcp-mode:` - MCP server mounting mode (string, default: `"default"`). Set to `"cli"` to mount each user-facing MCP serveras a standalone CLI tool on `PATH` so the agent can call MCP servers via shell (e.g. `github issue_read --method get ...`). The legacy `cli-proxy: true` is accepted for backward compatibility and migrated by `gh aw fix`. | ||
| - `mcp-mode:` - MCP exposure mode (string, default: `"default"`). Set to `"cli"` to mount each user-facing MCP server, including a selected GitHub MCP server, as a standalone CLI tool on `PATH`. This is distinct from `tools.github.mode`, does not select GitHub access, and does not provide the authenticated `gh` CLI. The legacy `cli-proxy: true` is accepted for backward compatibility and migrated by `gh aw fix`. |
gh-aw-bot
commented
Aug 17, 2026
@copilot this PR is ready for the next finishing pass. Please address these items, newest first:
Run: https://github.com/github/gh-aw/actions/runs/31996014734
|
Hey @lpcox 👋 — thanks for documenting the security profiles and GitHub access modes! This is a comprehensive update that clarifies important defaults, runner prerequisites, and migration paths. A few suggestions to strengthen this:
The documentation updates are focused and well-structured. If you'd like to automate the validation, you could assign this prompt to your agent:
|
gh-aw-bot
commented
Aug 17, 2026
@copilot this PR is ready for the next finishing pass. Please address these items, newest first:
Run: https://github.com/github/gh-aw/actions/runs/31997601784
|
Fixed in |
Addressed in |
gh-aw-bot
commented
Aug 17, 2026
@copilot this PR is ready for the next finishing pass. Please address these items, newest first:
Run: https://github.com/github/gh-aw/actions/runs/32004940993
|
Completed in |
gh-aw-bot
commented
Aug 17, 2026
@copilot this PR is ready for the next finishing pass. Please refresh the branch with the latest base changes if needed, rerun the Run: https://github.com/github/gh-aw/actions/runs/32019589269
|
Completed in |
gh-aw-bot
commented
Aug 17, 2026
@copilot this PR is ready for the next finishing pass. Please address these items, newest first:
Run: https://github.com/github/gh-aw/actions/runs/32026520939
|
Addressed all 11 review findings in |
gh-aw-bot
commented
Aug 17, 2026
@copilot this PR looks ready for the next maintainer-visible pass. Please address these items, newest first:
Run: https://github.com/github/gh-aw/actions/runs/32030687603
|
Fixed the stale-lock CI false positive in |
gh-aw-bot
commented
Aug 17, 2026
@copilot this branch is currently conflicting with
|
Resolved in |
gh-aw-bot
commented
Aug 17, 2026
@copilot this branch is currently conflicting with Run: https://github.com/github/gh-aw/actions/runs/32043948991
|
Resolved the |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
4107b56 to
cb469eeComparegh-aw-bot
commented
Aug 17, 2026
@copilot this PR is ready for the next finishing pass. Please address these items, newest first:
Run: https://github.com/github/gh-aw/actions/runs/32052943209
|
Summary
runtime-install, Cloud Hypervisor, Pi/non-MCP engines, integrity reactions, migrations, and invalid combinationsThis PR is stacked on #53236 and targets
lpcox-simplify-github-access.Validation
make agent-report-progressnode --test scripts/generate-schema-docs.test.jsnode scripts/generate-schema-docs.js(no generated frontmatter drift)cd docs && ./node_modules/.bin/astro build.github/awanddocs/src/content/docsNo workflow lock files changed.