Skip to content
AndonDocs
GitHub
Look something up

Repository settings (.andon/settings.json)

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

A team’s automation settings can live in its repository, so every Andon instance with a clone of that repository uses the same ones. Andon creates the file. What you change in Andon afterwards is an override for that instance only: Andon never rewrites the file.

On this page
View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

How it works

  • On each sync, the agent reads .andon/settings.json from the default branch of every clone linked to a team (origin/<branch> as last fetched, else the local branch), never from the files checked out. An edit in the clone, or a commit on another branch, changes nothing until it is merged to the default branch. A folder that isn’t a git repository, or has no default branch, reports nothing.

  • Only an admin’s machine applies the file. A file is applied only from a machine whose owner is an owner or admin of the workspace, since changing a team’s automation is an admin action. A member’s machine still writes the file where there is none (below), but what it reports changes nothing. A team whose clones are all on members’ machines keeps the file’s settings an earlier sync applied (none, for a new team) until an admin’s clone reports the file.

  • No file on the default branch: the agent writes one into the clone, untracked, unless the clone already has one. It holds the settings the team sets itself (not what it inherits from a parent team or the defaults, so those keep reaching it), or, once another clone has reported a file, that file’s settings: overrides made in Andon never go into it. Commit and merge it to share the settings. Remove it before switching to a branch that has one.

  • A file: its settings become the team’s base settings. What the team already sets in Andon stays and overrides the file: picking up a file never clears a value someone set. Clear a value on the team’s page to let the file decide it.

  • Changing the file waits for a person. .andon/settings.json is one of the standard never-auto-merge paths, so a pull request (or a merge without one) that changes it never merges on its own.

  • Overrides: a change in Settings → Teams, on a team (its level, model or subscription on the team’s page, or a setting found by searching Settings, such as Protect the standard paths), is saved in Andon and wins over the file, in that instance only. The setting then shows Overrides the repository’s .andon/settings.json here. Settings that come from the file show From the repository’s .andon/settings.json. On the team’s page, a row whose value comes from the file reads Repository: , and choosing that first option drops the team’s own value for it. No single button drops every override at once.

  • Which setting wins, from strongest to weakest:

    1. the team’s own setting in Andon;
    2. the team’s file;
    3. a parent team’s setting in Andon;
    4. the parent’s file;
    5. the workspace’s automation (changing it changes every team that sets nothing of its own);
    6. Andon’s defaults.

    A team stores a value only when it differs from what it would get from those: saving the inherited value stores nothing, and clearing a value returns the team to the inherited one.

  • A file Andon can’t use (bad JSON, an unknown key, a value out of range) shows its error under the team page’s Overrides. The last good settings stay in use until the file is fixed.

  • When a team has clones on more than one machine, the first admin’s clone to report a file provides it, until that clone leaves the team.

  • A file that isn’t on the default branch yet (untracked, uncommitted, or committed on another branch) and says something else than what the team runs with is called out under the team page’s Overrides: Your clone on has unmerged changes to .andon/settings.json: they apply once merged to , with each key that differs, its value in the file and the applied one. A key the team sets in Andon is marked as overriding the file, since merging won’t change it. The agent reports these clones with its heartbeat after each sync; a file that agrees with the applied settings (the one Andon wrote, say) says nothing. Only each team’s linked clone is read, not its worktrees: an edit in a card’s worktree applies once it is merged and the clone is on it.

  • The agent only touches clones inside the policy’s workspaceRoots. It never replaces an existing file and never follows a symlink.

The file

Most files are one line, a team preset:

JSON
{ "preset": "ship" }

preset is manual, assist or ship, the team’s level on its page. In the file it stands for the automation keys the preset sets:

preset autoReview autoMerge autoDone maxReviewRounds
manual false false false (as it is)
assist true false true (as it is)
ship true true true 2

A key under automation wins over the preset, so { "preset": "ship", "automation": { "maxReviewRounds": 3 } } is Ship with three rounds (still Ship on the team page: review rounds never change a team’s level). Whether cards are done by hand and Autopilot aren’t in the file: they belong to each Andon, set with the level on the team page. The file Andon writes says "preset" when the team’s own settings hold all of a preset’s keys, and lists under automation only what differs from it. An agent older than the preset key reports such a file as one it can’t use (unknown key): update it.

Every key in full:

JSON
{
"automation": {
"autoReview": true,
"autoMerge": true,
"mergeMethod": "squash",
"deleteBranch": true,
"maxReviewRounds": 2,
"maxCiFixAttempts": 2,
"neverMergePaths": ["infra/**"],
"deleteWorkspaceOnDone": true,
"autoDone": true,
"finishClassifier": true,
"reviewProvider": "claude",
"reviewModel": "default",
"runtime": "auto",
"executor": "claude",
"model": "default",
"reviewRequest": { "method": "comment", "reviewer": "review-bot", "comment": "@review-bot review", "waitMinutes": 60 }
}
}

Every key is optional. A missing key falls back to the parent team or the default. The values match the Runs and Pull requests sections: mergeMethod is squash, merge or rebase; reviewProvider and executor are claude, codex or gemini; runtime is auto, orca or terminal; a model is default or a model id; maxReviewRounds is 1 to 10 and maxCiFixAttempts is 0 to 10. reviewRequest asks another reviewer (a review bot, say) after Andon’s own review and fixes what it asks for: method comment, reviewer or off, the reviewer’s GitHub reviewer login, an optional comment and waitMinutes (5 to 1440, default 60).

runtime, finishClassifier and deleteWorkspaceOnDone have no control in Settings: where a card runs, judging unreported runs and deleting the workspace after Done are fixed behaviour. A file that sets them is still read, so leave them out to keep the fixed behaviour.

neverMergePaths adds to the standard paths; an empty list never removes them. While a team protects the standard paths (the default), a PR that changes any of these never merges on its own: supabase/migrations/**, db/migrations/**, .github/**, **/*.lock, **/pnpm-lock.yaml, **/package-lock.json, .env*, **/.env* and .andon/settings.json (the lockfile patterns don’t hold back Dependabot or Renovate PRs). On a repository with no GitHub remote, the same paths hold back Andon’s merge of a card’s branch into the base. The paths a team uses are the standard ones, then the nearest list (the team’s own in Andon, its file, a parent’s), so [] means the standard paths alone and a missing key falls back to the parent’s list. The file Andon writes, and the unmerged-file notice, hold only the additions; standard entries repeated in a file are harmless.

protectStandardPaths turns the standard paths off on purpose: with false, only what neverMergePaths adds still waits for a person, so a team that lists nothing protects nothing and its migrations, CI config, lockfiles, .env files and .andon/settings.json merge like any other change. It resolves like every other key (the team’s own in Andon, its file, a parent’s) and is on unless something says false. It is its own key because a saved [] once removed every protection without anyone meaning it. Search Settings for Protect the standard paths to find the switch, above the list, which shows the standard paths while they apply; turning it off asks first and lists what will then merge on its own (turning it back on doesn’t ask). A machine whose policy doesn’t allow auto merge still merges nothing, and a person’s Merge now still merges after a look.

Accounts (claude_account, codex_account) belong to a single instance and never go in the file. Nor does “When usage credits run out” (search Settings for it): its list names this instance’s accounts. Files from before that change may still hold creditsFallback; it is accepted and ignored.