mcp-gitlab-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP GitLab Usage

MCP GitLab 使用指南

Binding rules for GitLab MCP tool invocation. Tool schemas and detailed flows live in references — read them before calling tools.

GitLab MCP工具调用的约束规则。工具架构和详细流程请参考相关文档——调用工具前请先阅读。

Harness discovery

Harness 发现

See

../../ns-harness/references/harness-discovery.md

. For GitLab product config (status labels, project ids), read

{product_root}/docs/context/gitlab-sync-config.md

when it exists.

请参阅

../../ns-harness/references/harness-discovery.md

。对于GitLab产品配置（状态标签、项目ID），请在

{product_root}/docs/context/gitlab-sync-config.md

存在时阅读该文档。

FIRST ACTION (critical)

首要操作（至关重要）

When the human asks for requirements, planning, or issues in GitLab:

Your first action must be
```
start_execution_planning
```
with inferred arguments. Do not output planning text, RF suggestions, or issue descriptions before a tool response.
If MCP tools are unavailable: Say exactly that GitLab MCP is not available in this context. Do not output payloads that cannot be executed.

当用户在GitLab中请求需求、规划或Issue相关操作时：

你的首要操作必须是调用
```
start_execution_planning
```
并传入推断的参数。在获取工具响应前，请勿输出规划文本、RF建议或Issue描述。
**若MCP工具不可用：**明确告知当前环境中GitLab MCP不可用。请勿输出无法执行的负载内容。

First access and version check

首次访问与版本检查

When connecting to a GitLab MCP server that exposes

get_mcp_gitlab_skill

Call with
```
check_version: true
```
only.
Compare server version to any local MCP skill copy if present.
Call with
```
for_update: true
```
only when missing or versions differ.
Do not pass
```
check_version
```
and
```
for_update
```
together.

当连接到暴露

get_mcp_gitlab_skill

接口的GitLab MCP服务器时：

仅传入
```
check_version: true
```
调用该接口。
若存在本地MCP技能副本，将服务器版本与本地版本进行对比。
仅当本地版本缺失或版本不一致时，传入
```
for_update: true
```
调用该接口。
请勿同时传入
```
check_version
```
和
```
for_update
```
参数。

Mandatory practices

强制规范

Always pass
arguments
— never call tools with empty required fields.
Read tool schema before each unfamiliar call.
Never shortcut planning — run the full MCP flow; do not return "payloads for you to apply."
Project discovery:
```
git remote get-url origin
```
→ send path to MCP → use numeric
```
project_id
```
after human confirms full trio (
```
id
```
,
```
name
```
,
```
path_with_namespace
```
).

始终传入
arguments
参数——调用工具时切勿留空必填字段。
调用不熟悉的工具前，请先阅读工具架构。
切勿跳过规划流程——执行完整的MCP流程；请勿返回“供你自行应用的负载内容”。
**项目发现：**执行
```
git remote get-url origin
```
→ 将路径发送给MCP → 在用户确认完整三元组（
```
id
```
、
```
name
```
、
```
path_with_namespace
```
）后，使用数字格式的
```
project_id
```
。

Confirmation gates (non-negotiable)

确认环节（不可协商）

Cannot be inferred from context:

Flag	Set `true` only after
`requirements_confirmed`	Human says yes to validating requirements
`projects_confirmed`	Human confirms all project trios (main, backend, frontend)
`issues_creation_confirmed`	Human says yes to "Should I create the issues in GitLab?"

A broad request ("do everything") is not confirmation.

无法从上下文推断确认信息：

标志	仅在以下情况后设置为 `true`
`requirements_confirmed`	用户确认要验证需求时
`projects_confirmed`	用户确认所有项目三元组（主项目、后端项目、前端项目）时
`issues_creation_confirmed`	用户对“我是否应在GitLab中创建这些Issue？”回答“是”时

宽泛的请求（如“全部搞定”）不视为确认。

Execution sync (status labels)

执行同步（状态标签）

Three-step cycle per issue — never skip the middle step:

status_backlog → status_in_progress → status_done

Read label names from

gitlab-sync-config.md

or discover via

list_project_labels

. Full flow:

references/flows.md

SOURCE_BRANCH
for issue execution: resolved by

ns-execution-gitlab-issue

Gate 1 — milestone/version discovery with mandatory

develop

fallback (

../ns-execution-gitlab-issue/references/source-branch-resolution.md

). Do not pick a base branch ad hoc when delegating to that skill.

每个Issue需遵循三步循环——切勿跳过中间步骤：

status_backlog → status_in_progress → status_done

请从

gitlab-sync-config.md

中读取标签名称，或通过

list_project_labels

接口查询。完整流程请参阅

references/flows.md

。

**Issue执行的

SOURCE_BRANCH

：**由

ns-execution-gitlab-issue

的第1步确定——里程碑/版本发现，强制使用

develop

作为 fallback（详见

../ns-execution-gitlab-issue/references/source-branch-resolution.md

）。将任务委托给该技能时，请勿随意选择基础分支。

Delivery report

交付报告

Confirm issue target (
```
project_id
```
+
```
issue_iid
```
or URL).
Summarize diff vs agreed base branch.
```
add_issue_comment
```
with
```
internal: true
```
.

确认Issue目标（
```
project_id
```
+
```
issue_iid
```
或URL）。
总结与约定基准分支的差异。
调用
```
add_issue_comment
```
并设置
```
internal: true
```
。

Related skills

References

参考文档

File	When to read
`references/tool-catalog.md`	Before any tool call — required args and examples
`references/flows.md`	Planning, issue creation, execution sync, delivery report
`../ns-spec-driven/references/gates.md`	SDD planning gates
`../../ns-harness/references/artifact-layout.md`	`requirements.md` and version paths

文件	阅读时机
`references/tool-catalog.md`	任何工具调用前——包含必填参数和示例
`references/flows.md`	规划、Issue创建、执行同步、交付报告时
`../ns-spec-driven/references/gates.md`	SDD规划环节时
`../../ns-harness/references/artifact-layout.md`	`requirements.md` 和版本路径相关操作时

Error handling — STOP

错误处理——立即停止

Plan limit exceeded

or similar hard MCP errors: stop all GitLab operations, inform the human, wait for guidance. No workarounds.

当出现

Plan limit exceeded

或类似的MCP严重错误时：停止所有GitLab操作，告知用户，等待指导。请勿尝试变通方法。