Skip to content

Read-only guarantee

Reviewed repos are never modified. Local Review never fetches, checks out, commits, stashes, rebases or resets. It reads your repos the way git log does, so you can point it at a working checkout mid-task, with uncommitted changes, and nothing about the repo, its index or its branches changes.

All git access to the repos you review goes through one module, server/git.ts, which:

  • runs git -C <repo> … via execFile with no shell, so paths and refs can’t inject commands;
  • refuses any subcommand outside a read-only allow-list: log, show, diff, diff-tree, rev-list, rev-parse, merge-base, patch-id, cat-file, ls-tree, for-each-ref;
  • refuses options that write files or run programs (--output, --no-index, --ext-diff, --textconv, --filters, …);
  • only uses object-level commands: diffs are always commit-to-commit (git diff <parent> <sha>), never against the work tree or index, and git status is never run;
  • passes --no-optional-locks and sets GIT_OPTIONAL_LOCKS=0, so git never takes index locks or refreshes the index; drops any inherited GIT_* environment (e.g. GIT_DIR); and disables textconv, external diff drivers and signature checking;
  • only passes refs from project.yaml (checked: letters, digits and . _ / @ { } ^ ~ + - only, no leading -, no ..; after --end-of-options, or one per line on the stdin of git cat-file --batch-check) and full 40-hex shas that git itself returned. A landed PR’s shas from its prs file are used only after git has resolved them as commits (<sha>^{commit});
  • kills any git call that hasn’t finished within 60 seconds, so a git process stuck in the system can’t hang the server. The commands are read-only, so a killed one changes nothing.

One thing reads a reviewed repo without git: to tell whether any branch has moved, the branch poll (server/reffiles.ts) stats the files git keeps refs in (.git/HEAD, packed-refs, everything under refs/, and reftable/ if the repo uses it) and reads .git / commondir to find them in a worktree. It never opens anything for writing, and runs git (through server/git.ts) only when those change.

Two other git calls exist, and neither touches a repo you review:

  • Who you are. To name the reviewer, the server runs git config --get user.name once at start (see LOCAL_REVIEW_USER). It only reads.
  • The example projects. local-review examples creates four new repos under ~/.local-review/examples/ (git init, fast-import, a checkout of the new repo), and nothing else. They’re Local Review’s own data, never anyone’s work, and once made they’re only read, through server/git.ts like any other.

If you turn on GitHub status (it’s off by default), Local Review also reads GitHub, and only reads it. All of it goes through one module, server/gh.ts, which:

  • runs one command only, gh api graphql --hostname <host> --input -, via spawn with no shell, with the request on its stdin. The GitHub CLI holds your token; Local Review never sees or stores it;
  • refuses any request that isn’t a GraphQL query: anything with a mutation or subscription in it is refused before gh runs. So it can’t comment, approve, resolve, push or change anything on GitHub, whatever your token allows;
  • sends fixed query text, with only PR numbers in it, for the PRs your prs files record (github: {url}), with the owner and repo name from those URLs as variables;
  • refuses a host that could be read as an option (one starting with -), and kills a gh call that hasn’t finished in 60 seconds.

What it fetched is written only to its own cache, ~/.local-review/github/; never to your projects or repos.

  • Shas in URLs must be hex, and are only used after matching them against the repo’s own commit list.
  • Project and repo names are restricted to [A-Za-z0-9._-] with no leading dot, and must exist in the config.
  • Review and PR file names are restricted to <40-hex>.yaml.

So no request can name a path outside ~/.local-review/projects/.

Only your agent, in its own work: fixups, rebases, branches, pushes. Local Review shows the result, and never does any of it itself. Nor does it change anything on GitHub: with GitHub status on, it only reads.

Contributors: new git calls go through server/git.ts too, using only subcommands on the list, and GitHub calls through server/gh.ts, queries only. A change that weakens this won’t be merged (see Contributing).