docs: explain low-trust agents for GitHub review bots (#129)

GitHub review bots read code and conversation text supplied from outside
the company. This adds a dedicated section to the existing low-trust
review page explaining the agent preset, concrete work boundary,
isolated sandbox, governed connection tools, and the separate limits of
guest sponsorship.

The approved connector setup links to this existing page and warns when
the chosen agent uses standard trust. Choosing the warning does not
silently change the agent policy.

Validation: documentation build passed for 258 pages. No site
configuration or navigation changes.

Model: OpenAI GPT-6 through Codex, using repository inspection, editing,
and build tools; exact serving model ID/context size were not exposed.
This commit is contained in:
Dotta authored and GitHub committed 2026-09-21 12:43:29 -05:00
1 parent 480c133b1f
commit 8d83401d7b
1 file changed
+30
@@ -27,6 +27,36 @@ The default preset is `standard`; `low_trust_review` only takes effect when a po
---
## Choosing an agent for a GitHub bot
Use a dedicated low-trust review agent for pull requests and conversations that
can contain instructions from outside your company. Private repositories can
still contain untrusted code, comments, dependencies, and generated content.
Before connecting the agent:
1. Open the agent’s configuration and choose **Low-trust review** in its trust
settings.
2. Set a work boundary covering the review tasks, such as their dedicated project.
A preset without a concrete scope cannot run.
3. Configure isolated workspaces and an active sandbox environment in the runtime
settings. Low-trust API permissions do not sandbox a host-local process.
4. Allow only the tool capabilities needed for the work. Keep provider credentials
in governed connections, rather than embedding them in prompts or repository
files.
A bot connection’s caller permissions and its agent’s trust preset protect
separate boundaries. Giving an external GitHub user a restricted guest profile
is not a substitute for configuring the agent’s trust preset and runtime. A
responsible sponsor does not give the guest that sponsor’s personal credentials.
A setup warning does not change the selected agent’s permissions. If you continue
with a standard agent, review its existing access and runtime configuration: its
normal capabilities still matter when it reads outside content. Instructions
inside a PR must never be treated as permission to expand that access.
---
## How a preset is chosen
A low-trust preset is not a single switch. Paperclip resolves the effective preset by reading the same JSON policy you already use for execution, from up to four sources: