Skip to content

Refuse a start that still sets the retired EXCLUDE_TOOLS, as the retired read-only switches already do - #1092

Merged
jmrplens merged 7 commits into
issue-950-fairness-oauthfrom
issue-1045-retired-exclude-tools
Sep 30, 2026
Merged

jmrplens merged 7 commits into
issue-950-fairness-oauthfrom
issue-1045-retired-exclude-tools

Conversation

@jmrplens

@jmrplens jmrplens commented Sep 30, 2026 •

Copy link
Copy Markdown
Owner

Follows #1045.

#1045 made a stdio run refuse to start when it is given --exclude-tools, because ignoring the flag serves what the operator removed. It left one inconsistency open on purpose: the retired bare EXCLUDE_TOOLS, which 3.1.0 stopped reading, was still only named at WARN, so a deployment carrying EXCLUDE_TOOLS=project.delete started and served project.delete. config.RetiredEnvUses refuses the retired GITLAB_READ_ONLY and GITLAB_SAFE_MODE for exactly that reason. The answer to the open question was to refuse the retired exclusion too, and this layer does that.

What changed

config.protectionNames (internal/config/env_name.go) gains EXCLUDE_TOOLS, so RetiredEnvUses files it with the two retired switches it refuses rather than with the names it warns about. The three are the settings register row AUT-004 decides together, each withholding part of what the server serves, and the rule is the one the package already states: what ignoring the name would cost, not where it came from. Nothing else in the startup path changes: reportRetiredEnvNames in cmd/server already ends the run with exit code 1 before any transport starts when the refuse list is not empty, so the retired exclusion now stops a stdio and an HTTP start alike, with the refusal line the other two already print:

EXCLUDE_TOOLS is no longer read (removed in 3.1.0): rename it to GITLAB_MCP_EXCLUDE_TOOLS, and this deployment will not be started under a capability it did not ask for

The bare name refuses even though it may not be ours. EXCLUDE_TOOLS is generic enough that another tool in the same shell could own it, which is the reason the review of #1045 gave for waiting. The server cannot tell whose it is, and of the two guesses, the one that it belongs to somebody else is the guess that serves what an operator removed. The refusal costs whoever set it one variable renamed, or removed from the server's environment, and the documentation now says how.

The refusal reads the name, never the value, as it does for the other two: a retired GITLAB_READ_ONLY=false has always refused, and so does an EXCLUDE_TOOLS set to empty. That differs on purpose from the --exclude-tools flag, which is judged by what it asks for, because a retired name is not read at all and so nothing about its value can make ignoring it safe. The troubleshooting pages say to remove a foreign EXCLUDE_TOOLS with env -u rather than blank it.

Comments that named two refusing names now name three: reportRetiredEnvNames, httpOnlyFlags' doc comment, the bench driver's environment scrub and the HTTP e2e harness, whose list of stripped generic names had said "two of these retired names now stop the server starting" when neither of the two was on that list; EXCLUDE_TOOLS is.

No register row, value, refusal or site changes: this is a startup refusal of the operator's configuration, like the two it joins, and make check-tenancy reads the same 83 rows and 308 sites as the layer below.

Tests

  • internal/config: TestRetiredEnvUses_SplitsByWhatIgnoringOneWouldCost holds a retired exclusion to the refuse list, once naming an action and once set to empty, and its prefixed spelling to neither list. cmd/server's TestReportRetiredEnvNames_RefusesWhenAProtectionWasRetired covers all three names.
  • test/e2e/stdio/retired_env_test.go is new and holds the split against the binary, which nothing did: each of the three names, set once in the environment and once in the file GITLAB_MCP_ENV_FILE names, exits non-zero at ERROR with the refusal line, nothing on stdout and no "starting MCP server" line; a retired TOOL_SURFACE=individual is named at WARN and a gitlab_execute_action call is served, which also shows the value was ignored, since the individual surface would not register that tool. Nothing in the stdio module pinned the old warning, so no existing case changed; awaitRefusal now says "a setting" rather than "a flag", since it judges a variable too.
  • With the EXCLUDE_TOOLS entry removed from protectionNames, both exclusion cases of the new stdio test and the two refusing cases of the table test fail, and every other case passes.

Checks

Run on this branch at its last commit before the stack was rebased onto main at 50ef2cf, through the remote runner unless marked local. That base adds a serialtypecheck entry to a dependency list in cmd/server/main_test.go, which this layer also writes, and moves the README statistics and the testing reference, which this layer's refresh commit regenerated there. The stack now sits on b44ab96, which adds #1083, #1084 and #1085, none of which touches a file this stack writes, and every commit of the stack applied unchanged.

  • internal/config: go test -shuffle=on, 100.0% of statements; conditions (make coverage-conditions) 424/424; mutants (make coverage-mutants PKG=./internal/config, the whole package) 205 killed, 0 lived, 0 timed out, 9 not covered. The nine are arithmetic in config.go's package-level constant initializers (lines 21, 22, 40, 53 and 56: 2 * 1024 * 1024 * 1024, 24 * time.Hour and the like), a file this branch does not touch, and are the tool artifact the testing guide classifies: an initializer carries no statement counter. env_name.go has no survivor.
  • cmd/server and cmd/bench_resources: go test -shuffle=on, 100.0% of statements each. The change there is comments and one test table, so gremlins was not rerun on either; Warn at startup when a flag only HTTP mode reads is passed to a stdio server #1045's figures for cmd/server stand.
  • test/e2e/stdio, the whole module against a binary built from this tree (make test-e2e-stdio): 118 tests pass, the 107 of Warn at startup when a flag only HTTP mode reads is passed to a stdio server #1045 and the 11 added here.
  • golangci-lint with the e2e, httpe2e and stdioe2e tags over internal/config, cmd/server, cmd/bench_resources, test/e2e/stdio and test/e2e/http: clean. gofumpt and goimports (local): clean.
  • make check-tenancy (83 rows, 308 sites, 0 findings), check-doc-tool-names, check-test-file-names, check-test-subtests, check-test-goroutines, check-dead-consts: pass.
  • Local: markdownlint on every changed Markdown page, go run ./cmd/format_md_tables/ --check, and scripts/check-em-dash.sh against the layer below and against main: clean. No em or en dash in anything this layer adds.

Documentation

  • docs/reference/configuration.md, docs/reference/env.md and CLAUDE.md's Environment variables paragraph name three refusing names where they named two, and say why the bare one refuses and that the refusal reads the name and not the value.
  • docs/reference/cli.md still said the unprefixed spelling "still works and is removed in 3.1.0" and that the GITLAB_-prefixed switches keep their bare names; both were wrong since 3.1.0 and 2.8.0, and the paragraph now says what 3.1.0 does.
  • The site's configuration page, English and Spanish, had the same stale "still works" paragraph and listed the renamed GITLAB_MCP_ switches and GITLAB_MCP_YOLO_MODE among the names that "stay bare"; the section now matches the reference, with the refusal rule where the stale sentence was.
  • docs/guides/troubleshooting.md and the site's troubleshooting page, English and Spanish, gain a row for the refusal line: which names cause it, and the fix, including env -u EXCLUDE_TOOLS for one that belongs to another tool.

After review

  • RetiredEnvUses' comment stated a wider rule than the code applies: that refuse names any setting whose absence would leave the deployment able to do more than it was configured for. The code refuses the three names protectionNames holds, the settings AUT-004 decides together, and warns about every other retired name. The comment now says so, and names the retired bounds among the warnings. The set is not widened.
  • The collector harness (test/e2e/collector/harness_test.go) started the server with the whole inherited environment, so a foreign EXCLUDE_TOOLS exported in the developer's shell, which this layer turns into a refusal, would have failed every collector test at startup, as an exported GITLAB_READ_ONLY already did. It now filters the environment the way the HTTP module's harness does (GITLAB_ and OTEL_ names and the generic retired names) and passes GITLAB_MCP_LOG_LEVEL=info and GITLAB_MCP_TOOL_SURFACE=dynamic instead of the retired LOG_LEVEL and TOOL_SURFACE, which configured nothing. The module was compiled, vetted and linted with its tag; it skips on the remote runner, which has no Docker, so the filter was not driven against a collector.
  • A second review found the HTTP module in the same state, while its harness comment implied it was protected. Only startServer and runServerExpectingExit started from configFreeEnviron; shutdownStartServer and startServerWithClient passed the whole inherited environment, so with EXCLUDE_TOOLS=project.delete exported every TestListener_* test, the shutdown test on open listen streams and the probe, health and balancer cases built on those starters failed after about 45 seconds with "the server never became healthy". Both now start from configFreeEnviron, and every starter in the module passes GITLAB_MCP_LOG_LEVEL=info and GITLAB_MCP_TOOL_SURFACE=dynamic instead of the retired spellings, which configured nothing and only added a warning to each start; the values are the defaults. The harness comment says every starter does this. With EXCLUDE_TOOLS=project.delete exported, the whole test/e2e/http module passes through rgo (286 s), and the listener and shutdown tests pass without it too; go vet and golangci-lint with the httpe2e tag are clean.

Question left open

By the wider rule the old comment stated, four retired resource bounds would refuse too, and they warn: a retired UPLOAD_MAX_FILE_SIZE=10MB becomes the 2 GB default, RATE_LIMIT_RPS and RATE_LIMIT_BURST fall back to 10 and 40 in HTTP mode and to no limit on stdio, and MAX_HTTP_CLIENTS falls back to 100. Each was read bare by 2.7.5 and still honoured by 3.0.0. I have not decided whether they should refuse like the three protection names, which would widen protectionNames past AUT-004's three, or stay warnings, which keeps the rule as the comment now states it. This layer leaves them as warnings.

The top of the stack

This layer sits on the OAuth fairness layer, which added eight test files after the refresh #1045 carried, so it was the new top when written and carries the refresh in a commit of its own (the layer that records issue 951's decisions now sits above it and refreshes them once more): the README statistics and the testing reference move. The testing reference was regenerated with -skip-coverage, which carries the recorded coverage values forward and refreshes the counts and package rows the CI gate compares. The site stats, the llms files, the LobeHub manifest and the request inventory were checked and are unchanged, since no layer above #1045 moves the served surface or a request a handler sends.

Decisions I took here

  • The retired EXCLUDE_TOOLS refuses, as the question left by Warn at startup when a flag only HTTP mode reads is passed to a stdio server #1045's review was answered: the rule RetiredEnvUses applies is what ignoring a name would cost, and ignoring this one serves what the operator removed.
  • The refusal stays on presence, exactly as it is for GITLAB_READ_ONLY and GITLAB_SAFE_MODE, rather than on a value that names something as the --exclude-tools flag is judged. A second rule for one retired name would have to be explained on every page that states the first, and the value of a variable nothing reads cannot make ignoring it safe.
  • The refusal text is unchanged. It already reads correctly for an exclusion (serving an action the operator removed is starting "under a capability it did not ask for"), and rewording it would change the two existing refusals' lines for no gain.
  • A stdio e2e file was added although nothing there pinned the old warning, because the retired-name split had no hold against the binary at all, and the dotenv path is where a long-lived deployment keeps a retired name.
  • The site's stale "still works" paragraph and its table of bare names were corrected here rather than left, since they are the passage the refusal rule belongs in and contradicted it.

Not done

  • The coverage values in the testing reference are carried forward, not recomputed; a full make gen-testing-docs would measure them again.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @jmrplens, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 4 hours by commenting @sourcery-ai review. Upgrade to get a review now.

@coderabbitai

coderabbitai Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You'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.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: jmrplens/gitlab-mcp-server/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: a8c994f8-eb39-4b3e-ac35-2c2f3404a4dd

📥 Commits

Reviewing files that changed from the base of the PR and between e1e1669 and 6b6ffa0.

📒 Files selected for processing (23)
  • CLAUDE.md
  • README.md
  • cmd/bench_resources/target.go
  • cmd/server/http_only_flags.go
  • cmd/server/main.go
  • cmd/server/main_test.go
  • docs/development/testing/testing.md
  • docs/guides/troubleshooting.md
  • docs/reference/cli.md
  • docs/reference/configuration.md
  • docs/reference/env.md
  • internal/config/env_name.go
  • internal/config/env_name_test.go
  • site/src/content/docs/configuration.mdx
  • site/src/content/docs/es/configuration.mdx
  • site/src/content/docs/es/operations/troubleshooting.mdx
  • site/src/content/docs/operations/troubleshooting.mdx
  • test/e2e/collector/harness_test.go
  • test/e2e/http/harness_test.go
  • test/e2e/http/listener_test.go
  • test/e2e/http/shutdown_test.go
  • test/e2e/stdio/http_only_flags_test.go
  • test/e2e/stdio/retired_env_test.go

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@jmrplens
jmrplens added this pull request to stack #1095 September 30, 2026 10:18
@jmrplens jmrplens added the v3.1.0 Targeted at the 3.1.0 release label Sep 30, 2026
@jmrplens jmrplens added this to the 3.1.0 milestone Sep 30, 2026
@jmrplens jmrplens changed the title issue 1045 retired exclude tools Refuse a start that still sets the retired EXCLUDE_TOOLS, as the retired read-only switches already do Sep 30, 2026
@github-actions github-actions Bot added transport stdio and HTTP transports, the server process, and the transport e2e modules tooling The audit and generator commands under cmd/, and the Makefile targets that run them e2e The end-to-end suite and its Docker fixtures labels Sep 30, 2026
@jmrplens
jmrplens force-pushed the issue-1045-retired-exclude-tools branch from 4247120 to b43eb55 Compare September 30, 2026 12:05
EXCLUDE_TOOLS joins GITLAB_READ_ONLY and GITLAB_SAFE_MODE among the
retired names config.RetiredEnvUses refuses rather than warns about.
The three are the settings register row AUT-004 decides together:
each withholds part of what the server serves, so a version that
ignored one in silence would serve what the operator removed. Until
now a retired exclusion was only named and the excluded actions
served, while the --exclude-tools flag on stdio refused the start.

EXCLUDE_TOOLS is the one bare name of the three and may belong to
another tool in the same shell. It refuses all the same: the server
cannot tell whose it is, and guessing that it is somebody else's is
the guess that serves what was removed. The refusal reads the name
and never its value, as it does for the other two.

The table test holds the exclusion twice, set and set to empty, and
the server test adds it to the three refusing names. Comments that
named two refusing names now name three.
Nothing drove the retired-name split against a real process. The new
stdio case starts the binary with GITLAB_READ_ONLY, GITLAB_SAFE_MODE
and EXCLUDE_TOOLS each set, once in the environment and once in the
file GITLAB_MCP_ENV_FILE names, and holds each run to exit non-zero
at ERROR with the refusal line and nothing on stdout. A retired
TOOL_SURFACE=individual is held to the other half: named at WARN, and
a gitlab_execute_action call served, which the individual surface
would not register had the value been read.

With the EXCLUDE_TOOLS entry removed from config.protectionNames both
exclusion cases fail and the rest pass.

awaitRefusal now says "a setting" rather than "a flag", since it
judges a retired variable as well.
The configuration and environment references, CLAUDE.md and the site
configuration pages name three retired names that refuse the start
where they named two, and say why the bare EXCLUDE_TOOLS refuses even
though another tool could own it, and that the refusal reads the name
and never its value.

The CLI reference and the site configuration pages (English and
Spanish) still said the unprefixed spelling works until 3.1.0, and
the site listed the renamed GITLAB_MCP_ switches among the names kept
bare. Both now say what 3.1.0 does, and the site table matches the
reference.

The troubleshooting guide and the site troubleshooting pages gain a
row for the refusal line, which says to remove a foreign EXCLUDE_TOOLS
from the server's environment (env -u), since one set to empty is
still set and still refused.
The OAuth fairness layer and this one add tests and source after the
refresh the 1045 layer carried, so the README statistics and the
testing reference move again. The testing reference is regenerated
with -skip-coverage, which carries the recorded coverage values
forward and refreshes the counts and package rows the CI gate
compares. The site stats, the llms files, the LobeHub manifest and
the request inventory were checked and are unchanged.
Its comment said refuse names a setting whose absence would leave the
deployment able to do more than it was configured for. The code refuses
the three names protectionNames holds, the settings register row AUT-004
decides together, and warns about every other retired name, including
bounds whose absence does leave a deployment able to do more: a retired
UPLOAD_MAX_FILE_SIZE puts the 2 GB default back, and a retired
RATE_LIMIT_RPS no limit on stdio. A reader of the function could not
tell which rule it applies.

The comment now states the rule the code applies and names the retired
bounds among the warnings. The set is not widened here; whether those
bounds should refuse too is a question of its own.
… nothing

The collector harness started the binary with the whole inherited
environment plus LOG_LEVEL=info and TOOL_SURFACE=dynamic. Both are
retired spellings the server only warns about, so they configured
nothing, and since the retired EXCLUDE_TOOLS now refuses a start, as
GITLAB_READ_ONLY and GITLAB_SAFE_MODE already did, a developer with any
of them exported saw every collector test fail to start a server. An
inherited OTEL_SDK_DISABLED would have vetoed the telemetry every test
asserts on in the same way.

The harness now filters the inherited environment the way the HTTP
module's does, dropping GITLAB_ and OTEL_ names and the generic retired
names, and passes GITLAB_MCP_LOG_LEVEL and GITLAB_MCP_TOOL_SURFACE. The
variables a test passes are appended after the filter and still reach
the child.
…thing

This layer makes a retired EXCLUDE_TOOLS refuse the start, and the HTTP
module's harness comment says a developer who still exports it would
see every test fail to start a server, as if the module were protected.
Only startServer and runServerExpectingExit built the child's
environment from configFreeEnviron. shutdownStartServer and
startServerWithClient passed the whole inherited environment, so with
EXCLUDE_TOOLS=project.delete exported every TestListener_* test, the
shutdown test on open listen streams and the probe, health and
balancer cases built on those two starters failed after 45 seconds with
"the server never became healthy", the log naming the refusal.

Both now start from configFreeEnviron, as the collector module does.
Every starter also names its own settings as GITLAB_MCP_LOG_LEVEL and
GITLAB_MCP_TOOL_SURFACE: LOG_LEVEL and TOOL_SURFACE are retired names
that configured nothing and only added a warning to each start. The
values are the defaults, so no test's server changes. With
EXCLUDE_TOOLS exported the listener and shutdown tests pass.
@jmrplens
jmrplens force-pushed the issue-1045-retired-exclude-tools branch from b43eb55 to 6b6ffa0 Compare September 30, 2026 13:04
@sonarqubecloud

Copy link
Copy Markdown

@jmrplens
jmrplens merged commit 2719831 into main Sep 30, 2026
6 checks passed
@jmrplens
jmrplens deleted the issue-1045-retired-exclude-tools branch September 30, 2026 15:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

e2e The end-to-end suite and its Docker fixtures tooling The audit and generator commands under cmd/, and the Makefile targets that run them transport stdio and HTTP transports, the server process, and the transport e2e modules v3.1.0 Targeted at the 3.1.0 release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant