@zereight/mcp-gitlab 2.2.0 → 2.2.2

package/README.zh-CN.md

@@ -17,7 +17,7 @@
 
 ### 为什么使用这个 GitLab MCP？
 
-- **267 个工具 + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
+- **274 个工具：toolset 中 272 个 + `execute_graphql` + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
 - **MR 两步审查** — `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff`
 - **内置 Agent Skill** — `skills/gitlab-mcp/` 工作流指南
 - **认证灵活** — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
@@ -31,7 +31,7 @@
 | | @zereight/mcp-gitlab | GitLab MCP A（社区 CQRS 型） |
 |---|----------------------|------------------------------|
 | **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 |
-| **工具模型** | ~267 个细粒度工具 + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
+| **工具模型** | 274 个工具：toolset 中 272 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
 | **MR 审查** | 两步批量 diff | 因服务器而异 |
 | **Node.js** | >=18.17 | 通常 >=24 |
 | **许可证** | MIT | 因服务器而异 |
@@ -111,7 +111,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 
 示例使用 `zereight-mcp-gitlab`，这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它，请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
 
-如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.70`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.2.1`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -133,13 +133,13 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 
 - `--token` - GitLab Personal Access Token（替代 `GITLAB_PERSONAL_ACCESS_TOKEN`）
 - `--api-url` - GitLab API URL（替代 `GITLAB_API_URL`）
-- `--read-only=true` - 启用只读模式（替代 `GITLAB_READ_ONLY_MODE`，已弃用 — 推荐 `--permission-mode=readonly`）
+- `--read-only=true` - Deprecated (removed in next major (v3.0.0))；请改用 `--permission-mode=readonly`（替代 `GITLAB_READ_ONLY_MODE`）
 - `--permission-mode` - 权限级别：`readonly`、`modify`（禁用删除/拆除工具）或 `full`（替代 `GITLAB_PERMISSION_MODE`，默认 `full`）
 - `--toolsets=all` - 启用指定工具集（替代 `GITLAB_TOOLSETS`；未设置时使用精简 `core` 默认值）
 - `--tools=list_issues` - 添加单个工具（替代 `GITLAB_TOOLS`）
-- `--use-wiki=true` - 启用 Wiki API（替代 `USE_GITLAB_WIKI`，旧版 — 推荐 `GITLAB_TOOLSETS=wiki`）
-- `--use-milestone=true` - 启用里程碑 API（替代 `USE_MILESTONE`，旧版 — 推荐 `GITLAB_TOOLSETS=milestones`）
-- `--use-pipeline=true` - 启用流水线 API（替代 `USE_PIPELINE`，旧版 — 推荐 `GITLAB_TOOLSETS=pipelines`）
+- `--use-wiki=true` - Deprecated (removed in next major (v3.0.0))；请改用 `--toolsets=core,wiki`（替代 `USE_GITLAB_WIKI`）
+- `--use-milestone=true` - Deprecated (removed in next major (v3.0.0))；请改用 `--toolsets=core,milestones`（替代 `USE_MILESTONE`）
+- `--use-pipeline=true` - Deprecated (removed in next major (v3.0.0))；请改用 `--toolsets=core,pipelines`，并把 `validate_ci_lint,validate_project_ci_lint` 追加到现有 `--tools` 列表（如果还没有该列表，则设置 `--tools=validate_ci_lint,validate_project_ci_lint`）（替代 `USE_PIPELINE`）
 - `--disable-version-check=true` - 关闭启动时的新版本提示（替代 `GITLAB_DISABLE_VERSION_CHECK`）
 - `--masking-enabled=true` - 启用文本响应掩码（替代 `GITLAB_MASKING_ENABLED`）
 - `--masking-config` - 掩码配置文件路径（替代 `GITLAB_MASKING_CONFIG`）
@@ -147,6 +147,10 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 - `--masking-workspace-dir` - 用于解析掩码文件的目录（替代 `GITLAB_MASKING_WORKSPACE_DIR`）
 - `--compact-results=true` - 将过大的 MCP 工具回复截断为预览并附带 CLI 命令（替代 `GITLAB_MCP_COMPACT_RESULTS`，默认关闭）
 - `--compact-result-chars` - compact 字符阈值（替代 `GITLAB_MCP_COMPACT_RESULT_CHARS`，默认 `4000`）
+- `--compact-tools` - 以逗号分隔的工具名，仅在回复过大时对这些工具进行 compact，而不开启全局 compact（替代 `GITLAB_MCP_COMPACT_TOOLS`）
+- `--tool-profile` - `full`（默认）或 `slim`。`slim` 会从初始列表中移除 draft note、表情回应、标签、CI 目录工具以及 `create_group`。仅当 `GITLAB_TOOLSETS` 设置为非空白值时忽略（替代 `GITLAB_TOOL_PROFILE`）
+
+如果已经设置了 `GITLAB_TOOLSETS` 或 `--toolsets`，请把 `wiki`、`milestones` 或 `pipelines` 追加到该列表，不要整段替换。如果已经设置了 `GITLAB_TOOLS` 或 `--tools`，请把 `validate_ci_lint` 和 `validate_project_ci_lint` 追加到该列表，不要整段替换。显式列表会替换默认的 `core` toolset，不会合并。
 
 CLI 参数优先于环境变量。
 
@@ -156,16 +160,21 @@ CLI 参数优先于环境变量。
 
 > **细粒度工具过滤：**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新，同时阻止所有删除工具以及
 > 破坏性的拆除（teardown）工具（`cancel_pipeline`、`cancel_pipeline_job`、`stop_environment`、
-> `stop_stale_environments`、`unprotect_branch`）（包括通过 `execute_graphql` 的破坏性 mutation
+> `stop_stale_environments`、`unprotect_branch`、`unprotect_tag`）（包括通过 `execute_graphql` 的破坏性 mutation
 > —— 删除与拆除动词 —— 以及 `push_files` 的 `delete`/`move`），或使用
 > `GITLAB_PERMISSION_MODE=readonly` 只读运行。还可以用
 > `GITLAB_TOOLSETS=<group,…>` 启用工具分组，用 `GITLAB_TOOLS=<tool,…>` 白名单启用单个工具
 > （例如：只读分组 + 少数几个写工具），用 `GITLAB_DENIED_TOOLS_REGEX` 按正则屏蔽工具。
-> 旧版 `USE_GITLAB_WIKI` / `USE_MILESTONE` / `USE_PIPELINE` 标志仅为向后兼容保留。
+> 旧版 `USE_GITLAB_WIKI` / `USE_MILESTONE` / `USE_PIPELINE` 已弃用
+> （Deprecated, removed in next major (v3.0.0)）。
+> 请改用 `GITLAB_TOOLSETS=core,wiki`、`core,milestones` 或 `core,pipelines`
+> （`USE_PIPELINE` 还需要把 `validate_ci_lint,validate_project_ci_lint` 追加到现有 `GITLAB_TOOLS`，不要整段替换）。
+> 如果已经设置了 `GITLAB_TOOLSETS`，请把 toolset 追加到现有列表，不要整段替换。
+> 如果未设置 `GITLAB_TOOLS`，请设置 `GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint`。如果已经设置，请把 `validate_ci_lint,validate_project_ci_lint` 追加到现有列表，不要整段替换。
 > 参见 [Tools Reference](./docs/tools/index.md#feature-toggles) 和
 > [Environment Variables](./docs/configuration/environment-variables.md)。
 
-#### SSE
+- sse
 
 ```shell
 docker run -i --rm \
@@ -173,7 +182,7 @@ docker run -i --rm \
   -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
   -e GITLAB_PERMISSION_MODE=readonly \
-  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
+  -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
   -e SSE=true \
   -e SSE_AUTH_TOKEN=your_mcp_sse_token \
   -p 3333:3002 \
@@ -194,7 +203,7 @@ docker run -i --rm \
 }
 ```
 
-#### Streamable HTTP
+- streamable-http
 
 ```shell
 docker run -i --rm \
@@ -202,7 +211,7 @@ docker run -i --rm \
   -e REMOTE_AUTHORIZATION=true \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
   -e GITLAB_PERMISSION_MODE=readonly \
-  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
+  -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
   -e STREAMABLE_HTTP=true \
   -p 3333:3002 \
   zereight050/gitlab-mcp
@@ -522,7 +531,7 @@ node build/index.js
 | `MCP_SERVER_URL`                            | 是   | MCP 服务器的公开 HTTPS URL                                                                                                               |
 | `GITLAB_API_URL`                            | 是   | GitLab 实例 API URL（例如 `https://gitlab.com/api/v4`）                                                                                  |
 | `STREAMABLE_HTTP`                           | 是   | 必须为 `true`（不支持 SSE）                                                                                                              |
-| `GITLAB_OAUTH_SCOPES`                       | 否   | 要请求的 GitLab scopes，以逗号分隔。默认值为 `api`，当 `GITLAB_READ_ONLY_MODE=true` 时为 `read_api`。预注册应用必须配置至少这些 scopes。 |
+| `GITLAB_OAUTH_SCOPES`                       | 否   | 要请求的 GitLab scopes，以逗号分隔。默认值为 `api`；有效 permission mode 为 `readonly` 时为 `read_api`。预注册应用必须配置至少这些 scopes。 |
 | `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`        | 否   | Dynamic Client Registration（`POST /register`）的每客户端 IP rolling 限制。默认 `20`/小时，范围 `1`–`1000`。多个 IDE 窗口等导致注册被限流时可调高。与 GitLab API 限额无关。 |
 | `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | 否   | 仅用于本地 HTTP 开发                                                                                                                     |
 

package/build/auth-cli.js

@@ -1,7 +1,9 @@
 import * as os from "os";
 import * as path from "path";
+import { parseCliArgs } from "./cli-boolean-flags.js";
+import { deprecatedEnvInputFromSources, getDeprecatedEnvWarnings } from "./deprecated-env.js";
 import { GitLabOAuth } from "./oauth.js";
-import { createLogger } from "./utils/logger.js";
+import { createLogger, flushStartupLogs } from "./utils/logger.js";
 const logger = createLogger("gitlab-mcp-auth");
 const DEFAULT_API_URL = "https://gitlab.com";
 const DEFAULT_REDIRECT_URI = "http://127.0.0.1:8888/callback";
@@ -42,12 +44,12 @@ function readFlag(argv, name) {
 function wantsHelp(argv) {
     return argv.includes("--help") || argv.includes("-h");
 }
-function isReadOnlyMode(argv, env) {
-    const readOnly = readFlag(argv, "read-only") ?? env.GITLAB_READ_ONLY_MODE;
+function isReadOnlyMode(parsedArgs, env) {
+    const readOnly = parsedArgs["read-only"] ?? env.GITLAB_READ_ONLY_MODE;
     if (readOnly === "true") {
         return true;
     }
-    return (readFlag(argv, "permission-mode") ?? env.GITLAB_PERMISSION_MODE) === "readonly";
+    return (parsedArgs["permission-mode"] ?? env.GITLAB_PERMISSION_MODE) === "readonly";
 }
 export function gitlabOriginFromApiUrl(apiUrl) {
     return apiUrl.replace(/\/api\/v4\/?$/, "");
@@ -56,6 +58,14 @@ export async function runAuthCommandAsync(input = {}) {
     const argv = input.argv ?? process.argv;
     const env = input.env ?? process.env;
     const stdout = input.stdout ?? process.stdout;
+    const parsedArgs = parseCliArgs(argv.slice(2));
+    const warnings = getDeprecatedEnvWarnings(deprecatedEnvInputFromSources(parsedArgs, env));
+    for (const warning of warnings) {
+        logger.warn(warning);
+    }
+    if (warnings.length > 0) {
+        flushStartupLogs(logger);
+    }
     if (wantsHelp(argv)) {
         stdout.write(AUTH_CLI_HELP);
         return;
@@ -69,7 +79,7 @@ export async function runAuthCommandAsync(input = {}) {
         env.GITLAB_OAUTH_TOKEN_PATH ??
         path.join(os.homedir(), ".gitlab-mcp-token.json");
     const gitlabUrl = gitlabOriginFromApiUrl(apiUrl);
-    const scopes = [isReadOnlyMode(argv, env) ? "read_api" : "api"];
+    const scopes = [isReadOnlyMode(parsedArgs, env) ? "read_api" : "api"];
     const oauth = new GitLabOAuth({
         clientId,
         clientSecret: env.GITLAB_OAUTH_CLIENT_SECRET,

package/build/cli-boolean-flags.js

@@ -36,3 +36,37 @@ export function nextBooleanFlagValue(nextToken) {
     }
     return { value: "true", consumeNext: false };
 }
+/** Same flag parse as startup config: CLI values only, positionals ignored. */
+export function parseCliArgs(argv) {
+    const parsed = {};
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (!arg.startsWith("--")) {
+            continue;
+        }
+        const eqIndex = arg.indexOf("=");
+        if (eqIndex !== -1) {
+            const key = arg.slice(2, eqIndex);
+            const value = arg.slice(eqIndex + 1);
+            if (value) {
+                parsed[key] = value;
+            }
+            continue;
+        }
+        const key = arg.slice(2);
+        if (BOOLEAN_CLI_FLAG_NAMES.has(key)) {
+            const next = nextBooleanFlagValue(argv[index + 1]);
+            parsed[key] = next.value;
+            if (next.consumeNext) {
+                index += 1;
+            }
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            index += 1;
+            parsed[key] = next;
+        }
+    }
+    return parsed;
+}

package/build/config.js

@@ -1,35 +1,9 @@
-import { BOOLEAN_CLI_FLAG_NAMES, nextBooleanFlagValue } from "./cli-boolean-flags.js";
+import { parseCliArgs } from "./cli-boolean-flags.js";
+import { deprecatedEnvInputFromSources } from "./deprecated-env.js";
 import { parseToolProfile } from "./tools/tool-profile.js";
 import { parseCompactToolAllowlist } from "./utils/compact-tool-allowlist.js";
 // Parse CLI arguments before anything else
-const args = process.argv.slice(2);
-export const cliArgs = {};
-for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg.startsWith("--")) {
-        const eqIndex = arg.indexOf("=");
-        if (eqIndex !== -1) {
-            const key = arg.slice(2, eqIndex);
-            const value = arg.slice(eqIndex + 1);
-            if (value) {
-                cliArgs[key] = value;
-            }
-        }
-        else {
-            const key = arg.slice(2);
-            if (BOOLEAN_CLI_FLAG_NAMES.has(key)) {
-                const parsed = nextBooleanFlagValue(args[i + 1]);
-                cliArgs[key] = parsed.value;
-                if (parsed.consumeNext) {
-                    i += 1;
-                }
-            }
-            else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
-                cliArgs[key] = args[++i];
-            }
-        }
-    }
-}
+export const cliArgs = parseCliArgs(process.argv.slice(2));
 export function getConfig(cliKey, envKey, defaultValue) {
     return cliArgs[cliKey] || process.env[envKey] || defaultValue;
 }
@@ -103,7 +77,7 @@ export const GITLAB_OAUTH_SCOPES = GITLAB_OAUTH_SCOPES_RAW
         .filter(Boolean)
     : undefined;
 export const GITLAB_OAUTH_CALLBACK_PROXY = getConfig("oauth-callback-proxy", "GITLAB_OAUTH_CALLBACK_PROXY") === "true";
-/** @deprecated Use GITLAB_OAUTH_ALLOWED_GROUPS_RAW instead. Will be removed in the next major version. */
+/** @deprecated Use GITLAB_OAUTH_ALLOWED_GROUPS_RAW instead. Will be removed in v3.0.0. */
 export const GITLAB_ALLOWED_GROUPS_RAW = getConfig("allowed-groups", "GITLAB_ALLOWED_GROUPS");
 export const GITLAB_OAUTH_ALLOWED_GROUPS_RAW = getConfig("oauth-allowed-groups", "GITLAB_OAUTH_ALLOWED_GROUPS");
 export const GITLAB_OAUTH_ALLOWED_GROUPS = (() => {
@@ -202,5 +176,13 @@ export const HTTPS_PROXY = getConfig("https-proxy", "HTTPS_PROXY");
 export const NO_PROXY = getConfig("no-proxy", "NO_PROXY");
 export const NODE_TLS_REJECT_UNAUTHORIZED = getConfig("tls-reject-unauthorized", "NODE_TLS_REJECT_UNAUTHORIZED");
 export const GITLAB_CA_CERT_PATH = getConfig("ca-cert-path", "GITLAB_CA_CERT_PATH");
+/**
+ * Snapshot of deprecated settings for startup warnings.
+ * CLI flags win over env vars, matching getConfig, so the warning can name
+ * the flag the user actually passed.
+ */
+export function buildDeprecatedEnvInput() {
+    return deprecatedEnvInputFromSources(cliArgs, process.env);
+}
 const _poolMaxSizeRaw = getConfig("pool-max-size", "GITLAB_POOL_MAX_SIZE");
 export const GITLAB_POOL_MAX_SIZE = _poolMaxSizeRaw ? Number.parseInt(_poolMaxSizeRaw, 10) : 100;

package/build/deprecated-env.js

@@ -5,15 +5,116 @@ function shownEnvValue(rawValue) {
     }
     return `${singleLine.slice(0, 77)}...`;
 }
-function legacyToolsetWarning(envName, rawValue, toolset) {
+const REMOVAL_VERSION = "v3.0.0";
+const DEPRECATION_NOTICE_URL = "https://github.com/zereight/gitlab-mcp/issues/815";
+// USE_PIPELINE exposes these two tools, but they live in the `ci` toolset, not `pipelines`.
+// Suggesting `ci` would also turn on catalog tools the flag does not expose.
+const LEGACY_TOOLS_OUTSIDE_NAMED_TOOLSET = {
+    pipelines: "validate_ci_lint,validate_project_ci_lint",
+};
+function explicitToolsets(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        return undefined;
+    }
+    return trimmed;
+}
+function isAllToolsets(raw) {
+    return raw.trim().toLowerCase() === "all";
+}
+function settingName(envName, cliFlag, fromCli) {
+    if (fromCli) {
+        return `\`--${cliFlag}\` (${envName})`;
+    }
+    return envName;
+}
+function gitlabToolsAssignment(extraTools, toolsRaw, toolsFromCli) {
+    const prefix = toolsFromCli ? "--tools=" : "GITLAB_TOOLS=";
+    const existing = explicitToolsets(toolsRaw);
+    if (existing === undefined) {
+        return `${prefix}${extraTools}`;
+    }
+    const names = existing
+        .split(",")
+        .map(part => part.trim())
+        .filter(part => part.length > 0);
+    const merged = extraTools.split(",").reduce((current, tool) => {
+        if (current.includes(tool)) {
+            return current;
+        }
+        return [...current, tool];
+    }, names);
+    return `${prefix}${merged.join(",")}`;
+}
+function legacyToolsetHint(toolset, toolsetsRaw, toolsetsFromCli, toolsRaw, toolsFromCli, optional) {
+    const extraTools = LEGACY_TOOLS_OUTSIDE_NAMED_TOOLSET[toolset];
+    const toolsAssignment = extraTools === undefined
+        ? undefined
+        : gitlabToolsAssignment(extraTools, toolsRaw, toolsFromCli);
+    const listed = explicitToolsets(toolsetsRaw);
+    const toolsetsLabel = toolsetsFromCli && listed !== undefined ? "--toolsets" : "GITLAB_TOOLSETS";
+    if (listed !== undefined) {
+        const shown = shownEnvValue(listed);
+        // parseEnabledToolsets treats only the exact value "all" as every toolset.
+        // "all,pipelines" is not "all"; unknown token "all" is dropped and pipelines remains.
+        if (isAllToolsets(listed)) {
+            return `Keep the existing ${toolsetsLabel} value ("${shown}") and remove the deprecated setting`;
+        }
+        const extra = toolsAssignment === undefined ? "" : ` and set ${toolsAssignment}`;
+        if (optional) {
+            return (`Add \`${toolset}\` to the existing ${toolsetsLabel} list ("${shown}")${extra} ` +
+                "only if you want those tools");
+        }
+        return `Add \`${toolset}\` to the existing ${toolsetsLabel} list ("${shown}")${extra} instead`;
+    }
+    // An explicit toolset list replaces the default toolsets; it does not merge.
+    // Legacy USE_* flags add tools on top of defaults, so the hint must keep `core`
+    // only when the user has not set a toolset list.
+    const toolsets = `GITLAB_TOOLSETS=core,${toolset}`;
+    const replacement = toolsAssignment === undefined ? toolsets : `${toolsets} and ${toolsAssignment}`;
+    if (optional) {
+        return `Set ${replacement} only if you want those tools in addition to core`;
+    }
+    return `Use ${replacement} instead`;
+}
+function legacyToolsetWarning(envName, cliFlag, fromCli, rawValue, toolset, toolsetsRaw, toolsetsFromCli, toolsRaw, toolsFromCli) {
+    const name = settingName(envName, cliFlag, fromCli);
     if (rawValue === "true") {
-        return (`${envName} is deprecated and will be removed in the next major version. ` +
-            `Use GITLAB_TOOLSETS=${toolset} instead.`);
+        return (`${name} is deprecated and will be removed in ${REMOVAL_VERSION}. ` +
+            `${legacyToolsetHint(toolset, toolsetsRaw, toolsetsFromCli, toolsRaw, toolsFromCli, false)}.`);
     }
     const shown = shownEnvValue(rawValue);
-    return (`${envName} is set to "${shown}" and is deprecated. ` +
+    return (`${name} is set to "${shown}" and is deprecated and will be removed in ${REMOVAL_VERSION}. ` +
         `This value does not enable the ${toolset} toolset. Remove it. ` +
-        `Set GITLAB_TOOLSETS=${toolset} only if you want those tools enabled.`);
+        `${legacyToolsetHint(toolset, toolsetsRaw, toolsetsFromCli, toolsRaw, toolsFromCli, true)}.`);
+}
+function readOnlyRawValue(input) {
+    if (input.readOnlyRaw !== undefined && input.readOnlyRaw !== "") {
+        return input.readOnlyRaw;
+    }
+    if (input.readOnlyMode) {
+        return "true";
+    }
+    return undefined;
+}
+function readOnlyWarning(input) {
+    const raw = readOnlyRawValue(input);
+    if (raw === undefined) {
+        return undefined;
+    }
+    const name = settingName("GITLAB_READ_ONLY_MODE", "read-only", input.readOnlyFromCli === true);
+    if (raw === "true") {
+        const conflict = input.permissionModeRaw !== undefined && input.permissionModeRaw !== "readonly"
+            ? ` It OVERRIDES the configured permission mode "${input.permissionModeRaw}"; the server runs as "readonly".`
+            : "";
+        return (`${name} is deprecated and will be removed in ${REMOVAL_VERSION}. ` +
+            `Use GITLAB_PERMISSION_MODE=readonly or --permission-mode=readonly instead.${conflict}`);
+    }
+    return (`${name} is set to "${shownEnvValue(raw)}" and is deprecated and will be removed in ${REMOVAL_VERSION}. ` +
+        "This value does not enable legacy read-only mode. The effective permission mode comes from GITLAB_PERMISSION_MODE or --permission-mode. Remove it.");
 }
 /**
  * Builds startup warnings for deprecated env vars / CLI flags.
@@ -21,27 +122,72 @@ function legacyToolsetWarning(envName, rawValue, toolset) {
  */
 export function getDeprecatedEnvWarnings(input) {
     const warnings = [];
-    if (input.readOnlyMode) {
-        const conflict = input.permissionModeRaw !== undefined && input.permissionModeRaw !== "readonly"
-            ? ` It OVERRIDES the configured permission mode "${input.permissionModeRaw}"; the server runs as "readonly".`
-            : "";
-        warnings.push("GITLAB_READ_ONLY_MODE is deprecated and will be removed in the next major version. " +
-            `Use GITLAB_PERMISSION_MODE=readonly or --permission-mode=readonly instead.${conflict}`);
+    const readOnly = readOnlyWarning(input);
+    if (readOnly !== undefined) {
+        warnings.push(readOnly);
     }
     if (input.allowedGroupsRaw) {
+        const name = settingName("GITLAB_ALLOWED_GROUPS", "allowed-groups", input.allowedGroupsFromCli === true);
         warnings.push(input.oauthAllowedGroupsRaw
-            ? "GITLAB_ALLOWED_GROUPS is deprecated and ignored because GITLAB_OAUTH_ALLOWED_GROUPS is set. Remove it."
-            : "GITLAB_ALLOWED_GROUPS is deprecated and will be removed in the next major version. Use GITLAB_OAUTH_ALLOWED_GROUPS instead.");
+            ? `${name} is deprecated and ignored because GITLAB_OAUTH_ALLOWED_GROUPS is set. Remove it. It will be removed in ${REMOVAL_VERSION}.`
+            : `${name} is deprecated and will be removed in ${REMOVAL_VERSION}. Use GITLAB_OAUTH_ALLOWED_GROUPS instead.`);
     }
     const legacyToolsetFlags = [
-        [input.useWikiRaw, "USE_GITLAB_WIKI", "wiki"],
-        [input.useMilestoneRaw, "USE_MILESTONE", "milestones"],
-        [input.usePipelineRaw, "USE_PIPELINE", "pipelines"],
+        {
+            rawValue: input.useWikiRaw,
+            envName: "USE_GITLAB_WIKI",
+            cliFlag: "use-wiki",
+            fromCli: input.useWikiFromCli === true,
+            toolset: "wiki",
+        },
+        {
+            rawValue: input.useMilestoneRaw,
+            envName: "USE_MILESTONE",
+            cliFlag: "use-milestone",
+            fromCli: input.useMilestoneFromCli === true,
+            toolset: "milestones",
+        },
+        {
+            rawValue: input.usePipelineRaw,
+            envName: "USE_PIPELINE",
+            cliFlag: "use-pipeline",
+            fromCli: input.usePipelineFromCli === true,
+            toolset: "pipelines",
+        },
     ];
-    for (const [rawValue, envName, toolset] of legacyToolsetFlags) {
-        if (rawValue !== undefined) {
-            warnings.push(legacyToolsetWarning(envName, rawValue, toolset));
+    for (const flag of legacyToolsetFlags) {
+        if (flag.rawValue !== undefined) {
+            warnings.push(legacyToolsetWarning(flag.envName, flag.cliFlag, flag.fromCli, flag.rawValue, flag.toolset, input.toolsetsRaw, input.toolsetsFromCli === true, input.toolsRaw, input.toolsFromCli === true));
         }
     }
-    return warnings;
+    return warnings.map(warning => `${warning} See ${DEPRECATION_NOTICE_URL} for migration details.`);
+}
+function readSuppliedSetting(parsedArgs, env, cliKey, envKey) {
+    return parsedArgs[cliKey] || env[envKey];
+}
+/**
+ * Warning snapshot for one command. CLI flags in `parsedArgs` win over `env`,
+ * matching getConfig, and neither source is read from the process globals.
+ */
+export function deprecatedEnvInputFromSources(parsedArgs, env) {
+    const readOnlyRaw = readSuppliedSetting(parsedArgs, env, "read-only", "GITLAB_READ_ONLY_MODE");
+    return {
+        readOnlyMode: readOnlyRaw === "true",
+        readOnlyRaw,
+        readOnlyFromCli: Boolean(parsedArgs["read-only"]),
+        permissionModeRaw: readSuppliedSetting(parsedArgs, env, "permission-mode", "GITLAB_PERMISSION_MODE"),
+        allowedGroupsRaw: readSuppliedSetting(parsedArgs, env, "allowed-groups", "GITLAB_ALLOWED_GROUPS"),
+        allowedGroupsFromCli: Boolean(parsedArgs["allowed-groups"]),
+        oauthAllowedGroupsRaw: readSuppliedSetting(parsedArgs, env, "oauth-allowed-groups", "GITLAB_OAUTH_ALLOWED_GROUPS"),
+        useWikiRaw: readSuppliedSetting(parsedArgs, env, "use-wiki", "USE_GITLAB_WIKI"),
+        useWikiFromCli: Boolean(parsedArgs["use-wiki"]),
+        useMilestoneRaw: readSuppliedSetting(parsedArgs, env, "use-milestone", "USE_MILESTONE"),
+        useMilestoneFromCli: Boolean(parsedArgs["use-milestone"]),
+        usePipelineRaw: readSuppliedSetting(parsedArgs, env, "use-pipeline", "USE_PIPELINE"),
+        usePipelineFromCli: Boolean(parsedArgs["use-pipeline"]),
+        toolsetsRaw: readSuppliedSetting(parsedArgs, env, "toolsets", "GITLAB_TOOLSETS"),
+        toolsetsFromCli: Boolean(parsedArgs["toolsets"]),
+        toolsRaw: readSuppliedSetting(parsedArgs, env, "tools", "GITLAB_TOOLS"),
+        toolsFromCli: Boolean(parsedArgs["tools"]),
+    };
 }