Document sandbox and GitHub access profiles by lpcox · Pull Request #53442 · github/gh-aw

lpcox · 2026-08-17T18:00:45Z

Summary

add canonical sandbox runtime, GitHub access, and MCP exposure profile references
update authoring guidance, runtime docs, glossary, and navigation to use the profile model consistently
preserve the agentic-workflows skill route without carrying implementation, schema, or workflow migration changes from Simplify GitHub access modes #53236

Source documentation delta: #53283.

Caution

agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation.

Details

Potential security threats were detected in the agent output.

Review the workflow run logs for details.

Run: https://github.com/github/gh-aw/actions/runs/32057540470> Generated by 👨‍🍳 PR Sous Chef · gpt54 · 12.9 AIC · ⌖ 8.58 AIC · ⊞ 8.8K · ◷

_{Comment /souschef to run again}

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 894da70c-b0b5-49b6-be83-10f1320b6cf2

Copilot

Pull request overview

Documents the new sandbox, GitHub access, and MCP exposure profile model across user and workflow-authoring references.

Changes:

Adds canonical security-profile matrices and examples.
Updates terminology and migration guidance throughout documentation.
Adds navigation, skill routing, and a patch changeset.

Show a summary per file

File	Description
`docs/src/content/docs/reference/tools.md`	Documents MCP CLI exposure.
`docs/src/content/docs/reference/security-profiles.md`	Adds the profile reference.
`docs/src/content/docs/reference/sandbox.md`	Links runtime compatibility guidance.
`docs/src/content/docs/reference/integrity.md`	Updates integrity access requirements.
`docs/src/content/docs/reference/glossary.md`	Revises profile terminology.
`docs/src/content/docs/reference/github-tools.md`	Documents GitHub access modes.
`docs/src/content/docs/reference/frontmatter.md`	Links profile selection guidance.
`docs/src/content/docs/reference/engines.md`	Describes non-MCP engine behavior.
`docs/src/content/docs/reference/agent-runtimes.md`	Updates runtime compatibility details.
`docs/src/content/docs/introduction/architecture.mdx`	Distinguishes profile layers.
`docs/src/content/docs/guides/upgrading.md`	Adds migration guidance.
`docs/src/content/docs/examples/maintaining-repos.md`	Updates integrity terminology.
`docs/src/content/docs/engines/pi.md`	Revises Pi tool configuration.
`docs/astro.config.mjs`	Adds profile navigation.
`.github/skills/agentic-workflows/SKILL.md`	Adds profile routing.
`.github/aw/upgrade-agentic-workflows.md`	Updates upgrade examples.
`.github/aw/update-agentic-workflow.md`	Updates workflow-editing guidance.
`.github/aw/token-optimization.md`	Revises CLI optimization guidance.
`.github/aw/syntax-tools-imports.md`	Documents new tool selectors.
`.github/aw/syntax-agentic.md`	Updates syntax guidance.
`.github/aw/subagents.md`	Revises subagent tool access.
`.github/aw/security-profiles.md`	Adds authoring profile rules.
`.github/aw/release-workflow.md`	Updates release tool guidance.
`.github/aw/mcp-clis.md`	Revises MCP CLI configuration.
`.github/aw/github-mcp-server.md`	Updates GitHub MCP modes.
`.github/aw/github-agentic-workflows.md`	Updates workflow examples.
`.github/aw/designer.md`	Revises designer defaults.
`.github/aw/designer-mappings.md`	Updates intent mappings.
`.github/aw/create-agentic-workflow.md`	Revises creation guidance.
`.github/aw/agent-runtime-instructions.md`	Expands runtime guidance.
`.changeset/patch-document-security-profiles.md`	Records the documentation update.

Review details

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Suppressed comments (1)

docs/src/content/docs/reference/security-profiles.md:50

tools.mcp-mode is not a recognized tool setting in this PR. The current schema and ToolsConfig expose only tools.cli-proxy (main_workflow_schema.json:4932-4935, pkg/workflow/tools_types.go:87-93), so copying this profile causes schema validation to fail instead of enabling CLI wrappers. The field's implementation/schema support needs to land before it is documented as canonical.

`tools.mcp-mode: cli` exposes user-facing non-GitHub MCP servers as CLI wrappers on `PATH`. With the Copilot engine, it also wraps the GitHub MCP server when `mcp-local` or `mcp-remote` is selected; other MCP-capable engines keep the selected GitHub server as a native MCP server. 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.
The legacy `tools.cli-proxy: true` maps to `tools.mcp-mode: cli`. This field is unrelated to the internal host policy proxy used for CLI GitHub access.

Files reviewed: 31/31 changed files
Comments generated: 5
Review effort level: Balanced


 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 deprecated `features.cli-proxy` flag remains accepted for backward compatibility and 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.


 | `openai/` or `codex/` | `CODEX_API_KEY` or [`OPENAI_API_KEY`](/gh-aw/reference/auth/#openai_api_key) |

-Pi requires `tools.github.mode: gh-proxy` and `tools.cli-proxy: true`. The compiler rejects Pi workflows that omit either requirement.
+Pi does not provide native MCP server integration, so the compiler automatically derives CLI GitHub access (`tools.github.mode: cli`) and CLI MCP exposure (`tools.mcp-mode: cli`). Do not select `mcp-local` or `mcp-remote` for Pi, and do not add either derived field unless another workflow requirement makes it necessary.


+| `cli` | Pre-authenticated `gh` CLI protected by the host policy proxy; no GitHub MCP server | Shell-based GitHub access with the smallest tool schema; required by integrity reactions | Not supported by `cloud-hypervisor` |
+| `mcp-local` | Local Docker GitHub MCP server | GitHub MCP tools or MCP-only fields are required | Historical effective default when mode is omitted |
+| `mcp-remote` | Hosted GitHub MCP service | Hosted-only toolsets are required and suitable additional authentication is available | Do not use the GitHub Actions token as remote MCP authentication |


pelikhan · 2026-08-17T18:51:11Z

@copilot run pr-finisher skill

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-08-17T18:59:31Z

@copilot run pr-finisher skill

Fixed the three self-contained review issues (pushed in d3b..., see PR history): removed the contradictory toolsets example in pi.md, corrected the legacy mcp-servers example in upgrade-agentic-workflows.md to use mode: remote, and dropped the "default toolset" qualifier from CLI rows in create-agentic-workflow.md.

The remaining two threads (upgrading.md migration claims and security-profiles.md canonical names) point to a real scope conflict: the schema (pkg/parser/schemas/main_workflow_schema.json) and gh aw fix codemods still only support gh-proxy/local/remote, with no codemod producing cli/mcp-local/mcp-remote/tools.mcp-mode. Since this PR intentionally excludes the #53236 implementation/schema changes, fixing those two docs correctly means either bringing in that implementation or reverting the new terminology across the PR — that's a scope decision I can't make unilaterally, so I've left it as an open item rather than guessing. Local make fmt is clean after the changes.

gh-aw-bot · 2026-08-17T19:04:52Z

Caution

agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation.

Details

Potential security threats were detected in the agent output.

Review the workflow run logs for details.

@copilot thanks for the partial follow-up. Please run the pr-finisher skill again after a branch refresh if GitHub permits it. Two review items still look unresolved:

docs/src/content/docs/guides/upgrading.md — the guide still documents gh aw fix migrations that are not implemented by the current codemods: Document sandbox and GitHub access profiles #53442 (comment)
docs/src/content/docs/reference/security-profiles.md — the documented canonical names still do not match the schema/runtime currently in this PR: Document sandbox and GitHub access profiles #53442 (comment)

If the intended fix requires bringing in the #53236 implementation/schema work, say that explicitly in your follow-up so a maintainer can decide scope quickly.

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 12.9 AIC · ⌖ 8.58 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

Copilot · 2026-08-17T19:09:34Z

[!CAUTION]
agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation....

To be explicit: yes, fixing upgrading.md and security-profiles.md correctly requires bringing in the #53236 implementation/schema/codemod changes (canonical cli/mcp-local/mcp-remote values and tools.mcp-mode support don't exist in this PR's schema or gh aw fix registry). That's a scope decision for a maintainer, not something I can resolve unilaterally within this PR's stated boundaries, so I'm leaving those two threads open pending that call rather than making unscoped implementation changes or reverting the terminology myself.

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

gh-aw-bot · 2026-08-17T19:23:55Z

@copilot Please take another pass on this PR. Refresh the branch if possible, review any unresolved feedback, and run the skill before handing back to maintainers.

Run: https://github.com/github/gh-aw/actions/runs/32059494377

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 6.71 AIC · ⌖ 5.69 AIC · ⊞ 8.8K · ◷
_{Comment /souschef to run again}

Copilot · 2026-08-17T19:28:38Z

@copilot Please take another pass on this PR. Refresh the branch if possible, review any unresolved feedback, and run the skill before handing back to maintainers.
Run: https://github.com/github/gh-...

No new information here since my last reply. Status is unchanged: the three self-contained doc fixes are pushed, and the remaining two threads (upgrading.md, security-profiles.md) are blocked on a scope decision — they require bringing in the #53236 schema/codemod implementation to be fixed correctly, which is outside what I can resolve within this PR's stated boundaries. Deferring to a maintainer for that call.

Document sandbox and GitHub access profiles
b5bfa1b
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 894da70c-b0b5-49b6-be83-10f1320b6cf2

CopilotAI balanced review requested due to automatic review settings August 17, 2026 18:00

Copilotstarted reviewing on behalf of lpcox August 17, 2026 18:01 View session

lpcox closed this Aug 17, 2026

lpcox reopened this Aug 17, 2026

Merge branch 'main' into lpcox-document-sandbox-access-profiles
11a69f5

CopilotAI reviewed Aug 17, 2026
View reviewed changes

Copilotstarted work on behalf of pelikhan August 17, 2026 18:51 View session

Fix small doc inconsistencies flagged by review
239df78
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilotfinished work on behalf of pelikhan August 17, 2026 18:59

CopilotAI requested a review from pelikhan August 17, 2026 18:59

Merge branch 'main' into lpcox-document-sandbox-access-profiles
8c9eed1

github-actionsBot mentioned this pull request Aug 17, 2026
[pr-sous-chef] PR Sous Chef run report #53451
Closed

Copilotstarted work on behalf of gh-aw-bot August 17, 2026 19:05 View session

Apply remaining changes
41d4464
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilotfinished work on behalf of gh-aw-bot August 17, 2026 19:09

CopilotAI requested a review from gh-aw-bot August 17, 2026 19:09

Copilotstarted work on behalf of gh-aw-bot August 17, 2026 19:24 View session

Copilotfinished work on behalf of gh-aw-bot August 17, 2026 19:28

pelikhan closed this Aug 17, 2026

github-actionsBot added the closed:unknown PR was closed without merging: unknown label Aug 17, 2026

Navigation Menu

Uh oh!

Document sandbox and GitHub access profiles - #53442

Document sandbox and GitHub access profiles#53442
lpcox wants to merge 5 commits into
mainfrom
lpcox-document-sandbox-access-profiles

lpcox commented Aug 17, 2026•
edited by github-actions Bot
Loading

Uh oh!

CopilotAI left a comment

Uh oh!

Uh oh!

Uh oh!

pelikhan commented Aug 17, 2026

Uh oh!

CopilotAI commented Aug 17, 2026

Uh oh!

gh-aw-bot commented Aug 17, 2026

Uh oh!

CopilotAI commented Aug 17, 2026

Uh oh!

gh-aw-bot commented Aug 17, 2026

Uh oh!

CopilotAI commented Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		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 deprecated `features.cli-proxy` flag remains accepted for backward compatibility and 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.

Uh oh!

Conversation

lpcox commented Aug 17, 2026• edited by github-actions BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Uh oh!

Uh oh!

pelikhan commented Aug 17, 2026

Uh oh!

CopilotAI commented Aug 17, 2026

Uh oh!

gh-aw-bot commented Aug 17, 2026

Uh oh!

CopilotAI commented Aug 17, 2026

Uh oh!

gh-aw-bot commented Aug 17, 2026

Uh oh!

CopilotAI commented Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lpcox commented Aug 17, 2026•
edited by github-actions Bot
Loading