From 18f678d24eeb802a847d91c158c48c5b2eea1475 Mon Sep 17 00:00:00 2001 From: JSONbored <49853598+JSONbored@users.noreply.github.com> Date: Sun, 12 Jul 2026 06:47:28 -0700 Subject: [PATCH] docs(settings): cross-reference gateDryRun and agentDryRun Both fields use "dry run" vocabulary but gate two entirely disjoint layers with no shared code path. gateDryRun only computes an extra displayConclusion preview on the check-run -- the real posted conclusion is unaffected. agentDryRun switches the action-layer's execution mode to suppress real GitHub mutations -- entirely independent. Both fields are exposed side-by-side, unlinked, in the same maintainer-facing template. Added explicit cross-references at all four doc sites (2 types.ts fields + 2 byte-synced yml example files) so neither is mistaken for a sibling/superset of the other. Docs-only, no behavior change. Refs #5291 --- .gittensory.yml.example | 5 ++++- config/examples/gittensory.full.yml | 5 ++++- src/types.ts | 7 +++++-- 3 files changed, 13 insertions(+), 4 deletions(-) diff --git a/.gittensory.yml.example b/.gittensory.yml.example index d76e7049e1..f9812b8073 100644 --- a/.gittensory.yml.example +++ b/.gittensory.yml.example @@ -298,7 +298,9 @@ gate: # stricter verdict for AI-review blocker mode. It does not disable downstream # merge/close planning for failures from already-enforced gates. Bool. # Default: false. Config-as-code only — no DB column or dashboard toggle; - # this can only be set here. + # this can only be set here. Unrelated to settings.agentDryRun below despite + # the shared "dry run" name -- this only affects the check-run's display + # conclusion; it does NOT stop the agent action layer from real writes. dryRun: false # First-time-contributor grace. RESERVED / currently INERT: this value is @@ -690,6 +692,7 @@ settings: # Dry-run / shadow mode: suppresses the terminal GitHub-side write only. AI/LLM review calls still # execute and still incur their normal provider cost -- this is NOT a cost-free preview. + # Independent of gate.dryRun above -- the two "dry run" fields gate entirely disjoint layers. # Bool. Default: false. agentDryRun: false diff --git a/config/examples/gittensory.full.yml b/config/examples/gittensory.full.yml index f89e4d4079..dc779d2c7e 100644 --- a/config/examples/gittensory.full.yml +++ b/config/examples/gittensory.full.yml @@ -311,7 +311,9 @@ gate: # stricter verdict for AI-review blocker mode. It does not disable downstream # merge/close planning for failures from already-enforced gates. Bool. # Default: false. Config-as-code only — no DB column or dashboard toggle; - # this can only be set here. + # this can only be set here. Unrelated to settings.agentDryRun below despite + # the shared "dry run" name -- this only affects the check-run's display + # conclusion; it does NOT stop the agent action layer from real writes. dryRun: false # First-time-contributor grace. RESERVED / currently INERT: this value is @@ -703,6 +705,7 @@ settings: # Dry-run / shadow mode: suppresses the terminal GitHub-side write only. AI/LLM review calls still # execute and still incur their normal provider cost -- this is NOT a cost-free preview. + # Independent of gate.dryRun above -- the two "dry run" fields gate entirely disjoint layers. # Bool. Default: false. agentDryRun: false diff --git a/src/types.ts b/src/types.ts index 85dca132d0..4847bbd944 100644 --- a/src/types.ts +++ b/src/types.ts @@ -794,7 +794,9 @@ export type RepositorySettings = { expectedCiContexts?: ReadonlyArray | null | undefined; /** Dry-run disposition (#gate-dryrun). When true, the gate renders the would-be merge/close/manual verdict (every * advisory sub-gate promoted to block) WITHOUT enforcing — the posted check stays non-blocking. Lets advisory mode - * preview exactly what it would do before the maintainer flips to real enforcement. Default off. */ + * preview exactly what it would do before the maintainer flips to real enforcement. Default off. + * Unrelated to {@link agentDryRun} despite the shared "dry run" name -- this only affects the check-run's + * DISPLAY conclusion; it does NOT stop the agent action layer from performing real merges/closes/comments. */ gateDryRun?: boolean | undefined; /** Live premerge migrations/** collision recheck (#2550). When true, an agent-driven merge of a PR that * touches migrations/** is preceded by a fresh GitHub Trees-API read of the base branch's CURRENT migration @@ -1098,7 +1100,8 @@ export type RepositorySettings = { * performing any GitHub mutation -- but this is NOT a cost-free preview: AI/LLM review calls still * execute and still incur their normal provider cost (deliberate design tagged `#token-bleed-spend-gate` * in `ai-review-orchestration.ts`/`agent-orchestrator.ts`/`processors.ts`; every spend gate checks only - * `agentPaused`, never this field). Default false. */ + * `agentPaused`, never this field). Default false. Independent of the gate check's own {@link gateDryRun} + * preview -- the two "dry run" fields gate entirely disjoint layers with no shared code path. */ agentDryRun?: boolean | undefined; /** Per-repo override of the global DB-backed agent freeze (#4372): when true, this repo's actions execute * even while `global_agent_controls.frozen` is set, so an operator can re-activate one repo at a time