For developers · Orchestrator
Security model of the orchestrator
On this page
Gitoodo orchestrates coding agents as workers. A worker reads forge text (the issue, its comments) and runs code on the machine. This page says whose text may steer a worker, how a worker runs, and how the forge token stays out of the worker's reach. It answers the release-gate review findings H1 (untrusted forge text steering an unattended worker) and H2 (token-carrying git calls in worker-writable folders).
Who is trusted#
A login is trusted for a repository when any of these holds (intake::Intake::is_trusted, one rule
for intake, answers, briefs and worker context):
- it is the connected account (the bot) or one of Gitoodo's earlier write accounts of that forge
(
orchestrator_writers, #764); - it is the repository's configured human (
human); - it is listed in Settings → Dispatcher → Trusted authors (
trusted_authors); - the forge reports write, maintain or admin permission on the repository, or membership in the organisation that owns it.
A failed lookup counts as untrusted. Everyone else is untrusted, including anyone who can comment on a public repository.
What reaches a worker#
- Issue: only issues of trusted authors (or approved by a trusted person, spec 5.3) become
readyand are dispatched. Title and body of a dispatched issue reach the worker. - Comments, start brief (
orchestration::brief::worker_brief) **andgitoodo worker context**: only trusted people's comments appear as discussion, Gitoodo questions or answers. A comment of an untrusted person is never labelled "Answer" or "question", whatever markers it carries. Depending on the repo's worker mode (below) it is left out with a count (unattended) or quoted in a fence that its own backticks cannot close, under a heading that marks it as untrusted data (guarded; untrusted quotes have their own, smaller size budget, so they cannot push a trusted answer out). When trust cannot be judged (forge unreachable), every comment is left out. - Answers (
hygiene::reconcile_issue): only cards and answers posted by trusted people count. A stranger cannot post a card that names themselves and then answer it, and a stranger's answer marker or plain reply to a card without a header login does not release the issue. The intake's own approval and clarification rules (intake::scan) were already trust-checked; the issue author may still answer the intake's clarification. - Automations: only events of trusted actors start an automation session, and the prompt carries kind, number, author and link, never bodies. The title of an issue opened by an untrusted person is left out even when a trusted person's comment on it is the event.
The orchestrator chat (gitoodo mcp for a human-led chat session) still shows all comments: a
person reads along and confirms every write.
Worker mode per repository#
Settings → Repositories → (repo) → "Workers with permission checks" sets worker_permissions in
orchestration.json:
| Mode | Agent flags | Untrusted comments |
|---|---|---|
unattended (default) | Claude Code --dangerously-skip-permissions; Codex exec --dangerously-bypass-approvals-and-sandbox; Gemini --yolo | left out |
guarded | Claude Code --permission-mode auto --add-dir <clone git dir>; Codex exec --sandbox workspace-write with network access and the clone's git directory as an extra writable root; Gemini --yolo --sandbox --include-directories <clone git dir> | quoted as untrusted data |
unattended stays the default because workers must finish without anyone answering prompts, and
it is safe for the trust boundary above: only trusted text reaches it. guarded adds the agent's own
checks as a second line, for repositories where more is at stake, typically public ones. Automation
sessions always run unattended; their prompts carry only trusted text. Satellites get the same mode;
the clone's git directory is only added on the main host.
Public repositories#
On a public repository anyone can open issues and comment. Untrusted issues wait for a trusted
person's approval and are never dispatched on their own. Untrusted comments never steer a worker in
either mode. What remains is the code and data in the repository itself (a trusted person merged
it) and whatever a worker fetches from the internet while it works; for that second line, use
guarded.
Worker follow-up issues#
A worker may propose a follow-up issue (gitoodo worker follow-up, spec 8.3); the dispatcher's broker
creates it with the connected account's token. The worker's text is treated as untrusted data,
although the bot account is its author:
- Mediated: the proposal needs the worker's capability, a live lease of that worker on its issue
and the repo setting
worker_follow_ups(on by default; switch it off where workers should never write to the issue tracker). The worker gets no token and no forge client. - Bounded: one-line title up to 200 characters, body up to 16 KiB, at most
dispatch.max_follow_ups_per_runper run (default 3) and 10 per repository and hour; a title that matches an open issue refuses the proposal. Refusals name only fixed reasons, never forge errors. - Not ready on its own: the issue carries the
gitoodo:follow-upmarker in the footer Gitoodo appends;<!--in the worker's text is defused, so it cannot forge that or any other Gitoodo marker. The intake sees the marker and asks the repo's human for approval like for an issue from outside (a "no" closes it); the read model never counts it ready without thereadylabel. Only after that approval does its body reach another worker. With the intake rule for outside issues switched off, follow-ups wait untouched. - Labels: besides the intake label
gitoodo, only an existing label that is no workflow, priority, host or release label may be added, so a worker cannot route, prioritise or release its own proposals.
Residual risk: the text is public on the forge before anyone approves it, and @mentions in it
notify the people named, like any issue the bot opens. A worker that runs wild can open at most the
budget above before a human sees it; switch the setting off for repositories where that matters.
Forge token and git (H2)#
A worker controls its worktree and, through the shared git directory, the clone's configuration and hooks. No token-carrying git process runs there:
- Every token-carrying git call (
fetch_base,push_branch,push_assigned_branch, the leased push of a branch update, the backup push of the hygiene,remote pruneof the maintenance, the first clone, the prefetch of missing objects before a worktree is cut) runs throughcrates/core/src/token_git.rs:GIT_DIRis a scratch bare directory under Gitoodo's temp root with a configuration Gitoodo writes (hooks off, no fsmonitor, the explicit remote URL), objects come from the clone's object store (GIT_OBJECT_DIRECTORY), the refs it needs are seeded. The clone's own config, hooks,insteadOf/pushInsteadOfrewrites, filters, credential helpers and includes are never read. - On top:
GIT_CONFIG_NOSYSTEM=1,GIT_CONFIG_GLOBAL=/dev/null, every inheritedGIT_*variable removed (exceptGIT_SSL_CAINFO/GIT_SSL_CAPATH),-c core.hooksPath=/dev/null -c core.fsmonitor=false -c credential.helper= -c core.askPass=, submodule recursion and auto-maintenance off, andGIT_ALLOW_PROTOCOLlimited to the remote's scheme (https, http). - Local steps in the checkout (
update-ref, rebase or merge of an update,worktree add) run without any token in their environment; they may run the worker's hooks, which then see nothing secret. gitoodo askpassanswers only prompts that name the forge host of the push or fetch (GITOODO_ASKPASS_HOST); any other prompt gets nothing.- Proxies:
http.proxyand other proxy settings from git config files are not used, since the global and system config is dropped. A proxy comes from the service environment (HTTPS_PROXY,HTTP_PROXY,NO_PROXY), which git honours; a custom CA fromGIT_SSL_CAINFO. Gitoodo does not set-c http.proxy=(an empty value would switch the environment proxy off). On Windows the token calls usehttp.sslBackend=schannel, the system certificate store. - Inside a worker (
GITOODO_ISSUEset)gitoodo worker push|pr,gitoodo askand the MCP tools only work through the dispatcher's broker (the capability inGITOODO_WORKER_CAPABILITY) or, on a satellite, through the main host. Without a capability they refuse; they never read the keychain token there. - A headless service that gets its tokens as
GITOODO_TOKEN_*takes them out of its environment at start and keeps them in memory, so no child (git, hooks, agents) inherits them. Managed workers start with a cleaned environment in any case.
Limits: a worker runs as the same operating-system user. In unattended mode it can do whatever
that user can, including starting other programs; the trust boundary keeps strangers from steering
it, it does not sandbox it. guarded relies on the agent's sandbox for that.
Not covered by the change: LFS filters and other settings from the user's global git config no longer apply to the token-carrying calls (the first clone included); a clone that needs Git LFS fetches its LFS objects on the first local checkout step.