Repository navigation
Say at startup which HTTP-only flags a stdio run ignores, and refuse the ones it cannot ignore safely - #1090
Conversation
There was a problem hiding this comment.
Sorry @jmrplens, your pull request is larger than the review limit of 150,000 diff characters
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 59 minutes. View limit detailsLimit details: You’ve used the included review currently available. Review configuration: ⚙️ Run configurationConfiguration used: Repository: jmrplens/gitlab-mcp-server/.coderabbit.yaml Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (27)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
716fb58 to
bac52a8
Compare
Every flag main registers into httpConfig is parsed on every run, and a stdio run never reads that struct: main hands runWithContext a nil one unless the transport is HTTP, and runStdio builds its configuration from config.Load and the environment alone. So a stdio user who passed --rate-limit-rps=5 to switch the limiter on got no limiter and no message, and one who passed --read-only got a server that writes. A stdio run now says so, once, after the transport is explained: one WARN line naming each such flag with the variable stdio reads instead where there is one. Under --transport=auto the same line is written at INFO, because that command line was written for either transport; the container image's own command carries --http-addr, and a warning on every `docker run -i` session would teach the reader of that log to skip warnings. --read-only and --safe-mode asking to hold back writes refuse the start instead, with the variable to set named. They are the two settings config.RetiredEnvUses refuses a retired spelling of, for the same reason: ignoring either serves writes on a deployment that asked for reads, and the stdio servers most likely to carry one are the ones an MCP client started with nobody reading their stderr. Set to false they ask for nothing to be held back and are only named. httpOnlyFlags is held to the registrations into httpConfig by a test that reads the package's source in both directions, so a flag added to the HTTP configuration cannot be left out; another test holds each variable it names to a change in what config.Load returns, so the advice cannot name a variable stdio does not read. The retired-name report, the transport line and this check now run from one function, since main was at the limit the maintainability check accepts. test/e2e/stdio holds all three behaviours against the binary, the ignored bucket included. The help's FLAGS section says which flags a stdio server reads, and the two test comments that gave the stdio rate-limit reason as latency now give the one the rest of the tree states: a limiter there refuses and never delays, so it would only refuse its one user's own calls. Closes #1045.
Twelve places said stdio accepts --rate-limit-rps and ignores it without a warning, which stopped being true with the startup line the previous commit adds. They now say stdio ignores the flag and says so at startup, naming the variable instead. The CLI reference and the site's configuration page (English and Spanish) state the rule for the whole HTTP table rather than for one row: every flag in it but --http is read in HTTP mode only, a stdio run given one names it at WARN (INFO under --transport=auto), and --read-only or --safe-mode asking to hold back writes refuses the start with exit code 1. The --action-timeout row loses "does nothing", the exit code table names the new refusal, CLAUDE.md states the rule beside the HTTP flag table, and D8 of the September documentation audit, which left the warning as a code decision, records how issue 1045 resolved it.
gremlins reported every `config.EnvPrefix + "..."` in the httpOnlyFlags initializer, and the two concatenated line constants, as mutants no test covers: a concatenation in a package-level initializer is folded by the compiler, so no test can reach the mutated form. Each is now one literal. TestHTTPOnlyFlags_NameVariablesStdioReads already holds every variable spelling to one config.Load reads, and the unit and stdio e2e tests read the lines word for word, so nothing the concatenation guarded is lost.
…itlab-url The review of this change found the refusal set chosen by analogy with the retired-name table rather than by the rule that table states, which is what ignoring a value would cost. Two flags cost more than a setting when a stdio run ignores them, and both only warned: - --exclude-tools names tools the operator asked not to exist, and register row AUT-004 decides it together with --read-only and --safe-mode. A stdio run given --exclude-tools project.delete logged one line and served project.delete. - --gitlab-url is read in HTTP mode only, and a stdio run connects to the instance GITLAB_URL names, https://gitlab.com when it is unset. An MCP client configured with --gitlab-url for a self-managed instance and that instance's token in its environment sent the token to gitlab.com at startup, before any tool was called. HTTP mode refuses to choose an instance for a caller for exactly this reason. Both now refuse the start, under --transport=auto too: --exclude-tools when it names anything (read with config.ParseCSV, as both transports read it), and --gitlab-url when none of the instances it names is the one stdio connects to, compared in the canonical form the HTTP allow-list uses, so a flag naming that same instance however it is spelled is only reported. The instance stdio connects to is resolved the way config.Load resolves it, and a test holds the two together. The refusal line of the withholding flags now holds when the variable is already set beside the flag, which is still refused, as a retired name is beside its replacement: it says the flag has no effect and asks for it to be removed, rather than that the server would serve what it withholds. --max-request-body-bytes names GITLAB_MCP_STDIO_MAX_LINE_BYTES, the stdio ceiling on the same inbound message, instead of saying stdio has no such setting. The variable test reads what stdio reads at startup, config.Load and the transport's own limits, and a second test holds each variable to the flag it is named for through the HTTP environment overlay, which a table sending --tier to GITLAB_MCP_TOOL_SURFACE would have passed before. Under --transport=auto only a flag stdio has no setting for at all is named at INFO; a setting stdio has a variable for stays at WARN, since a command line written once for either transport plausibly meant it for both. The curated help lists -allow-private-instances and -description-substitutions, which it never did, and TestPrintHelp_DocumentsEveryFlag reads the env-backed flags from their table so that cannot recur. helpEntry matches a line that starts with the name, since the help's stdio paragraph now names flags.
The stdio rule now refuses a start for --exclude-tools as well as --read-only and --safe-mode, and for a --gitlab-url naming no instance the stdio run connects to, and names only the flags stdio has no setting for at INFO under --transport=auto. The pages that state the rule follow it: - CLAUDE.md said every flag of the HTTP table lands in httpConfig, which the four telemetry rows of that same table contradict; the sentence now leaves them out and states the refusals by what ignoring them costs. - The CLI reference said every flag below -http is read in HTTP mode only, which the -tool-search and -probe rows of the same page contradict; it now says a server serving HTTP is the only reader, and lists both refusals. - The configuration reference gained the stdio rule in its HTTP Server Mode introduction, the refusals beside the retired-name ones, and a transport qualifier on the flags in its loading order. - The environment reference says which of its flags a stdio run reads. - The troubleshooting guide and the site's troubleshooting pages (English and Spanish) list the two new startup failures with what to set instead, and the site's configuration pages state the refusals. - The -rate-limit-rps row of the CLI reference and the rate-limit row of the Copilot instructions say stdio names the flag at startup, as the rest of the tree does. - The documentation audit's D8 resolution records the final rule. A re-padded troubleshooting row carried an em dash; it is rewritten without.
The four layers below leave the committed artifacts to the top of the stack. Regenerated here: the README statistics and the testing reference, which count the tests this stack adds. The golden snapshots, the llms files, the token footprint, the request inventory, the LobeHub manifest and the site stats were regenerated too and came out unchanged, since no layer moves the served surface or a request a handler sends. CLAUDE.md and docs/development/cmd-utilities.md take the text the layers proposed rather than wrote: the identity cache and verification ceiling of issue 950 (ADM-005, ADM-014) in the environment table, the flag table and the OAuth routing section; the held-call ceiling (HLD-011) and the stateful session ceiling (HLD-010) of issue 951 in the same three places and in the bench_resources line, with its held and sessions modes and their make targets. The routing section now counts the nine invariants it lists.
bac52a8 to
8649b06
Compare
|



Every flag
mainregisters intohttpConfigis parsed on every run, and a stdio run never reads that struct:mainhandsrunWithContexta nil one unless the transport is HTTP, andrunStdiobuilds its configuration fromconfig.Loadand the environment alone. So a stdio user who passed--rate-limit-rps=5to switch the limiter on got no limiter and no message, one who passed--read-onlygot a server that writes, and one whose client configuration carried--gitlab-url https://gitlab.corp.examplewith the corporate token in its environment sent that token tohttps://gitlab.com, the instance stdio falls back to whenGITLAB_URLis unset, at startup and before any tool was called.docs/development/documentation-audit-2026-09.md(D8) found the same for--action-timeoutand left the warning as a code decision.What a stdio run does now. Once the transport is explained, it names every flag it was given that lands in
httpConfig, each with the variable stdio reads instead where there is one (--rate-limit-rps (on stdio set GITLAB_MCP_RATE_LIMIT_RPS),--max-request-body-bytes (on stdio set GITLAB_MCP_STDIO_MAX_LINE_BYTES), the line ceiling that bounds the same inbound message,--http-addr (stdio has no such setting)), and goes on ignoring them:WARNwhen the operator chose stdio, by default, with--transport=stdioor with--http=false;--transport=auto, a flag stdio has no setting for at all (the listener, the pool, the authentication gate) atINFOon a line of its own, since that command line was written for either transport and the container image's own command carries--http-addr: a warning on everydocker run -isession of the published image would teach the reader of that log to skip warnings. A flag stdio has a variable for stays atWARNthere, since a setting written once for either transport was plausibly meant for both.The flags that refuse instead. The condition is what ignoring the value would cost, the rule
config.RetiredEnvUsesapplies to the retired variable names. Ignoring most of these flags costs a setting. Two kinds cost more, and a stdio run given one exits 1 before serving, under--transport=autoas well, with oneERRORline each naming the flag and what to set instead:--read-onlyor--safe-modeset totrue, or an--exclude-toolsnaming anything: the three settings register rowAUT-004decides together, each withholding part of what the server serves, so ignoring one serves it (set_instead=GITLAB_MCP_READ_ONLY=true,GITLAB_MCP_EXCLUDE_TOOLS=project.delete).--gitlab-urlnone of whose instances is the one the stdio run connects to: ignoring it sendsGITLAB_TOKENto an instance the command line did not name, which is the reason HTTP mode refuses to choose an instance on a caller's behalf, applied here to the operator (set_instead=GITLAB_URL). The comparison is in the canonical form the HTTP allow-list uses, so a--gitlab-urlnaming that same instance however it is spelled is only named, and the instance stdio connects to is resolved the wayconfig.Loadresolves it.A value that asks for nothing (
--read-only=false, an--exclude-toolsof blanks, an empty--gitlab-url) costs nothing when ignored and is only named. A refused flag is refused even when its variable already asks for the same thing, as a retired name is beside its replacement, and the refusal line is worded to hold then too: the flag has no effect here, so set the variable and remove the flag.How the set is kept.
httpOnlyFlagsincmd/server/http_only_flags.gonames each flag with its stdio variable and, for the four above, the refusal.TestHTTPOnlyFlags_AreTheFlagsBoundToHTTPConfigreads the package's source for everyflag.XxxVar(&hcfg.field, ...)and holds the table to it in both directions.TestHTTPOnlyFlags_NameVariablesStdioReadssets each named variable to two values and requires what stdio reads at startup,config.Loadand the transport's own limits, to differ.TestHTTPOnlyFlags_NameEachFlagsOwnVariableholds each variable to the flag it is named for, through the HTTP environment overlay: set to two values with no flag passed, the one field it moves must be the field the flag is registered into, which a table sending--tiertoGITLAB_MCP_TOOL_SURFACEfails (checked by making exactly that edit).--max-request-body-bytes, whose stdio variable HTTP mode has no variable for, is declared with its reason and held to moving nothing. The retired-name report, the transport line and this check run from one function,reportStartupConfiguration, sincemainwas at the limit the maintainability linter accepts.test/e2e/stdio/http_only_flags_test.goholds the behaviors against the binary:--rate-limit-rps=0.001 --rate-limit-burst=1named atWARNand still ignored (three tool calls served, no limiter line); the image's--transport auto --http-addr 0.0.0.0:8080named atINFOwith no warning, and a--tool-surfaceadded to it named atWARN;--read-only,--read-onlybesideGITLAB_MCP_READ_ONLY=true, and--exclude-toolseach exiting 1 before serving with nothing on stdout; a--gitlab-urlnaming another instance exiting 1 with the instanceGITLAB_URLnames counting that no request reached it; and a--gitlab-urlnaming the same instance with a trailing slash served and named.The curated
-hsays which flags a stdio server reads and which it refuses, and now lists-allow-private-instancesand-description-substitutions, which it never did;TestPrintHelp_DocumentsEveryFlagreads the env-backed flags from their table so that cannot recur. The twocmd/servertest comments that gave the stdio rate-limit reason as latency, which issue #1045 lists as its own work because #959's layer could not editcmd/server, now give the one the rest of the tree states: the limiter refuses and never delays, so on stdio it would only refuse its one user's own calls (the same comment ininternal/config/config.gowas #1042's, which main now carries). Twelve documentation lines that said stdio ignores--rate-limit-rps"without a warning" are corrected, and the CLI and configuration references, the environment reference, the troubleshooting guide and the site's configuration and troubleshooting pages (English and Spanish), the exit-code table,CLAUDE.mdand.github/copilot-instructions.mdstate the rule.internal/tenancy/decisions_allow.go(RTC-001) still says stdio accepts the flag and ignores it, which stays true; changing register text would make this a register change for no gain.Not a limit. No register row, value, refusal or site changes: the refusal is a startup refusal of the operator's configuration, like the retired-name one, and not a refusal of a caller.
make check-tenancypasses unchanged. The validation checklist therefore has nothing to answer: VAL-001 to VAL-009 describe a row there is none of, VAL-010 has no telemetry to carry, VAL-011 is this change (stdio is where it acts), and VAL-012 has no population to protect and no measurement to take.Verified
Measured on this layer before it was rebased onto main at 5da9699, where main's server card change (#1061) sits in the same file; the two merged without a conflict. At its place in this stack on 50ef2cf, the layer built and vetted, the e2e gitlab, http and stdio packages compiled, the unit suites of
cmd/server,internal/tenancy,internal/oauthandcmd/audit_tenancypassed, andmake check-tenancyread the same 83 rows and 308 sites as the layer below. The stack now sits on b44ab96, which adds #1083, #1084 and #1085; they change the upstream register, indirect module versions and the site's package pins, none of them a file this stack writes, and every commit of the stack applied unchanged.cmd/server, shuffled: coverage 100.0% of statements; race on the new and neighboring tests;go vet;golangci-lint --build-tags e2eand--build-tags stdioe2eclean.cmd/server(a staged copy without the non-Linux twins, since gobco cannot instrument the package in place): 2118 of 2160 conditions both ways. The 42 left are the base's 42 at the same code (2082 of 2124 before this change); every condition this change adds,http_only_flags.gowhole, is evaluated both ways.--workers 2 --timeout-coefficient 20) overcmd/server, scoped to the two files this change writes, at the layer's last commit before the rebase: 367 killed, 4 lived, 25 not covered, 0 timed out.http_only_flags.gohas no survivor. All 29 are inmain.go, none on a line this change writes, and they are the base's set on the same code shifted by the help text added here.main.gotherefore does not meet the gate on its own. Its 11 one-way conditions, 4 lived and 25 not-covered mutants are carried to The condition gate cannot instrument cmd/server: gobco panics on build-constrained duplicates #1017, whosecmd/serverhalf is the package's closing pass, with the list; most of the not-covered ones are arithmetic in constant initializers, the classhttp_only_flags.goremoved by spelling its variables out.test/e2e/stdio, the whole module against the binary built from this tree: pass.test/e2e/gitlab/commonandtest/e2e/httpcompile.make check-tenancy,check-dead-consts,check-test-file-names,check-test-subtests,check-test-goroutines,check-doc-tool-names,check-em-dashagainst bothmainand the layer below: pass.format_md_tables --checkandmarkdownlint-cli2on the changed pages: clean.The top of the stack
This layer was the top of the tenancy stack (#950, the two parts of #951 and this one) when it was written, so it also carries the refresh of the committed artifacts the layers below leave stale, in its own commit; the layers since stacked above it refresh them again at the new top. The README statistics and the testing reference move, since the stack adds tests; the golden snapshots, the llms files, the token footprint, the request inventory, the LobeHub manifest and the site stats were regenerated and came out unchanged, since no layer moves the served surface or a request a handler sends.
CLAUDE.mdanddocs/development/cmd-utilities.mdtake the text the lower layers proposed: the identity cache and verification ceiling (ADM-005,ADM-014) and the held-call and stateful session ceilings (HLD-011,HLD-010) in the environment table, the HTTP flag table and the OAuth routing section, and thebench_resourcesheld and sessions modes with their make targets.At the top, with the freshness gates checked rather than deferred: every check of CI's generated-artifacts job passes (
check-openplugin,check-stats,check-doc-links,check-plan-untrackedandcheck-em-dashrun locally, the rest on the remote runner), as docheck-e2e-static,check-tenancy,check-request-inventoryand the e2e harness's own tests; the whole unit suite passes (275 packages); golangci-lint with thee2e,httpe2eandstdioe2etags overcmd/audit_tenancy,cmd/bench_resources,cmd/server,internal/oauth,internal/tenancy,test/e2e/httpandtest/e2e/stdioreports nothing; the unit suites of those packages pass shuffled twice;test/e2e/httppasses (605 tests, the 7 Docker-only proxy and balancer cases skipped) andtest/e2e/stdiopasses (107 tests), both against the binary built at the top; markdownlint is clean on every page the stack changes.Decisions I took here
--read-onlyand--safe-modeset to true, an--exclude-toolsnaming anything, and a--gitlab-urlnaming no instance stdio connects to refuse a stdio start (exit 1) instead of warning. The issue allows a warning or a refusal; the ruleconfig.RetiredEnvUsesalready applies to the retired names is what ignoring the value would cost, and nobody reads a stdio server's stderr.EXCLUDE_TOOLSrefuses as well, by the same rule: ignoring it serves what the operator removed, exactly as ignoring--exclude-toolsdoes. The rule lives inconfig.protectionNamesininternal/config, so a layer of its own higher in this stack makes that change, beside the retiredGITLAB_READ_ONLYandGITLAB_SAFE_MODEit already refused.--transport=autoa flag stdio has no setting for is named at INFO, not WARN, because the published image's own command passes--http-addrand a warning would fire on everydocker run -isession. A flag with a stdio variable stays at WARN there, and the refusals apply under auto too.check-tenancyis unchanged.httpConfig, held in both directions by a test that reads the source.--tool-surface,--tierand--tls-certare also read by--tool-searchand--probe, which exit before a transport is chosen.--gitlab-urlis compared in the canonical form the HTTP allow-list uses; an empty value, or one naming the same instance however it is spelled, is only named, and a spelling either side cannot normalize matches nothing and refuses. The instance stdio connects to is resolved incmd/serverthe wayconfig.Loadresolves it (trimGITLAB_URL, fall back toconfig.DefaultGitLabURL), held together byTestStdioInstance_IsTheOneConfigLoadResolves, rather than by exporting config's resolver.httpOnlyFlagsare written as literals, not asconfig.EnvPrefixplus a name, so gremlins has no unreachable initializer mutants there; a test holds each spelling to a variableconfig.Loadreads.reportRetiredEnvNames, the transport line and this check run from one function,reportStartupConfiguration, in that order, to keepmainunder the maintainability limit.CLAUDE.mdwas edited in this layer (theGITLAB_MCP_RATE_LIMIT_RPSrow and the paragraph before the HTTP flag table), because the issue is about that text. The orphaned test comment for aTestRateLimit_DefaultsDifferByTransportthat does not exist was removed with its stale latency reason.docs/development/documentation-audit-2026-09.mdis marked "Resolved by issue 1045" rather than by a release number, which is not known yet.Not done
GITLAB_MCP_READ_ONLYfrom--read-only, for instance); that would change stdio's configuration model beyond what the issue asks, so it names or refuses them instead.internal/tenancy/decisions_allow.go(RTC-001) still says stdio accepts--rate-limit-rpsand ignores it, which stays true; changing register text would make this a register change for no gain.main.godoes not meet the house gate on its own: its 11 one-way conditions, 4 lived and 25 not-covered mutants predate this change and are carried to The condition gate cannot instrument cmd/server: gobco panics on build-constrained duplicates #1017'scmd/serverhalf with the list.Closes #1045.