From 3e1bbf562fe927e80a122970b0e310ffaba481ac Mon Sep 17 00:00:00 2001 From: JSONbored <49853598+JSONbored@users.noreply.github.com> Date: Sun, 12 Jul 2026 06:40:26 -0700 Subject: [PATCH] docs(settings): document that publicSurface doesn't suppress either check-run publicSurface governs only shouldPublishPrComment/shouldApplyPrLabel -- neither the Context check (checkRunMode) nor the Gate check (reviewCheckMode) is ANDed with it, confirmed end-to-end in processors.ts. This is intentional (#2852: the check-run must keep posting for branch-protection/auto-merge to keep working) and already correctly documented in registration-readiness.ts's maintainer-facing readiness report -- but had no doc comment on the field itself, and no caveat on any of the 4 openapi occurrences. Docs-only, no behavior change. Regenerated openapi.json. Refs #5288 --- apps/gittensory-ui/public/openapi.json | 12 ++++++++---- src/openapi/schemas.ts | 24 ++++++++++++++++++++---- src/types.ts | 5 +++++ 3 files changed, 33 insertions(+), 8 deletions(-) diff --git a/apps/gittensory-ui/public/openapi.json b/apps/gittensory-ui/public/openapi.json index a9eb9eb9d..cca6da238 100644 --- a/apps/gittensory-ui/public/openapi.json +++ b/apps/gittensory-ui/public/openapi.json @@ -3837,7 +3837,8 @@ "comment_and_label", "comment_only", "label_only" - ] + ], + "description": "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run." }, "commentMode": { "type": "string", @@ -9211,7 +9212,8 @@ "comment_and_label", "comment_only", "label_only" - ] + ], + "description": "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run." }, "includeMaintainerAuthors": { "type": "boolean" @@ -9714,7 +9716,8 @@ "comment_and_label", "comment_only", "label_only" - ] + ], + "description": "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run." }, "commentMode": { "type": "string", @@ -10128,7 +10131,8 @@ "comment_and_label", "comment_only", "label_only" - ] + ], + "description": "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run." }, "commentMode": { "type": "string", diff --git a/src/openapi/schemas.ts b/src/openapi/schemas.ts index e92af604c..7cbcdcbc9 100644 --- a/src/openapi/schemas.ts +++ b/src/openapi/schemas.ts @@ -779,7 +779,11 @@ export const RepositorySettingsSchema = z gittensorLabel: z.string(), blacklistLabel: z.string().nullable(), createMissingLabel: z.boolean(), - publicSurface: z.enum(["off", "comment_and_label", "comment_only", "label_only"]), + publicSurface: z + .enum(["off", "comment_and_label", "comment_only", "label_only"]) + .describe( + "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run.", + ), includeMaintainerAuthors: z.boolean(), requireLinkedIssue: z.boolean(), backfillEnabled: z.boolean(), @@ -859,7 +863,11 @@ export const RepoSettingsPreviewSchema = z repoFullName: z.string(), generatedAt: z.string(), settings: z.object({ - publicSurface: z.enum(["off", "comment_and_label", "comment_only", "label_only"]), + publicSurface: z + .enum(["off", "comment_and_label", "comment_only", "label_only"]) + .describe( + "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run.", + ), commentMode: z.enum(["off", "detected_contributors_only", "all_prs"]), publicAudienceMode: z.enum(["oss_maintainer", "gittensor_only"]), publicSignalLevel: z.enum(["minimal", "standard"]), @@ -1258,7 +1266,11 @@ export const InstallationRepairSchema = z repoFullName: z.string(), isRegistered: z.boolean(), settings: z.object({ - publicSurface: z.enum(["off", "comment_and_label", "comment_only", "label_only"]), + publicSurface: z + .enum(["off", "comment_and_label", "comment_only", "label_only"]) + .describe( + "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run.", + ), commentMode: z.enum(["off", "detected_contributors_only", "all_prs"]), publicAudienceMode: z.enum(["oss_maintainer", "gittensor_only"]), checkRunMode: z.enum(["off", "enabled"]), @@ -2173,7 +2185,11 @@ export const RegistrationReadinessSchema = z docsCompleteness: z.record(z.string(), z.unknown()), githubApp: z.object({ installed: z.boolean(), - publicSurface: z.enum(["off", "comment_and_label", "comment_only", "label_only"]), + publicSurface: z + .enum(["off", "comment_and_label", "comment_only", "label_only"]) + .describe( + "Governs ONLY the PR comment and label -- never the Gittensory Context check (checkRunMode) or the Gittensory Orb Review Agent gate check (reviewCheckMode), which are independent axes by design (#2852). Setting this to \"off\" does NOT silence either check-run.", + ), commentMode: z.enum(["off", "detected_contributors_only", "all_prs"]), publicAudienceMode: z.enum(["oss_maintainer", "gittensor_only"]), checkRunMode: z.enum(["off", "enabled"]), diff --git a/src/types.ts b/src/types.ts index 85dca132d..bb2f9c2ce 100644 --- a/src/types.ts +++ b/src/types.ts @@ -944,6 +944,11 @@ export type RepositorySettings = { * settings.advisoryAiRouting` in shared/global or per-repo config. Defaults all-false so every advisory * capability stays on the shared frontier env.AI chain until an operator opts each one in. */ advisoryAiRouting?: AdvisoryAiRoutingConfig | undefined; + /** Governs ONLY the PR comment and label -- never the "Gittensory Context" check ({@link checkRunMode}) + * or the "Gittensory Orb Review Agent" gate check ({@link reviewCheckMode}), which are independent axes + * by design (#2852: the check-run must keep posting for branch-protection/auto-merge to keep working + * even when a maintainer wants full public silence). Setting this to `"off"` does NOT silence either + * check-run -- see README's "Check-run and comment surfaces, disambiguated" section. */ publicSurface: "off" | "comment_and_label" | "comment_only" | "label_only"; includeMaintainerAuthors: boolean; /** Surfaces the `missing_linked_issue` advisory finding in the review comment -- does NOT block a PR on