Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Orchestrator

Security model of the orchestrator

On this page
  1. Who is trusted
  2. What reaches a worker
  3. Worker mode per repository
  4. Public repositories
  5. Worker follow-up issues
  6. Forge token and git (H2)

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 ready and are dispatched. Title and body of a dispatched issue reach the worker.
  • Comments, start brief (orchestration::brief::worker_brief) **and gitoodo 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:

ModeAgent flagsUntrusted comments
unattended (default)Claude Code --dangerously-skip-permissions; Codex exec --dangerously-bypass-approvals-and-sandbox; Gemini --yololeft out
guardedClaude 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_run per 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-up marker 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 the ready label. 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 prune of the maintenance, the first clone, the prefetch of missing objects before a worktree is cut) runs through crates/core/src/token_git.rs: GIT_DIR is 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/pushInsteadOf rewrites, filters, credential helpers and includes are never read.
  • On top: GIT_CONFIG_NOSYSTEM=1, GIT_CONFIG_GLOBAL=/dev/null, every inherited GIT_* variable removed (except GIT_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, and GIT_ALLOW_PROTOCOL limited 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 askpass answers only prompts that name the forge host of the push or fetch (GITOODO_ASKPASS_HOST); any other prompt gets nothing.
  • Proxies: http.proxy and 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 from GIT_SSL_CAINFO. Gitoodo does not set -c http.proxy= (an empty value would switch the environment proxy off). On Windows the token calls use http.sslBackend=schannel, the system certificate store.
  • Inside a worker (GITOODO_ISSUE set) gitoodo worker push|pr, gitoodo ask and the MCP tools only work through the dispatcher's broker (the capability in GITOODO_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.

Docs version: dev