ns-gitlab-board-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitLab Board Sync

GitLab Board 同步

Mirror local SDD planning/execution state onto existing GitLab issues. Does not create issues.

将本地SDD规划/执行状态镜像到现有GitLab issues中。不支持创建新issues。

Prerequisites

前置条件

GitLab MCP available — follow
```
mcp-gitlab-usage
```
for all tool calls
If multiple GitLab MCP servers: ask human which to use

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

validated

For post-planning batch:
```
gitlab-issue-feature-map.md
```
exists

需具备可用的GitLab MCP —— 所有工具调用请遵循
```
mcp-gitlab-usage
```
规范
若存在多个GitLab MCP服务器：询问相关人员使用哪一个

已验证

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

配置文件

规划后批量同步场景：需存在
```
gitlab-issue-feature-map.md
```
文件

Configuration

配置说明

Read

references/gitlab-sync-config.template.md

for expected fields:

```
project_id
```
,
```
milestone_id
```
,
```
assignee_default
```

status_backlog

status_in_progress

status_done

status_blocked

rf_label_format

base_branch

work_branch

mr_target_branch

Discover unknown status labels via

list_project_labels

— confirm with human.

请阅读

references/gitlab-sync-config.template.md

了解所需配置字段：

```
project_id
```
、
```
milestone_id
```
、
```
assignee_default
```

status_backlog

、

status_in_progress

、

status_done

、

status_blocked

rf_label_format

、

base_branch

、

work_branch

、

mr_target_branch

可通过

list_project_labels

查询未知状态标签——需与相关人员确认。

Flow C — Pre-implementation read

流程C —— 预实施读取

When task lists GitLab issue IIDs:

```
read_issue
```
for description + recent comments
Non-blocking if inaccessible — log warning, continue
Do not mutate issue in this flow

当任务列表包含GitLab issue IID时：

调用
```
read_issue
```
获取描述及最新评论
若无法访问则不阻塞流程——记录警告并继续执行
此流程中请勿修改issue

Flow A — Post-planning batch

流程A —— 规划后批量同步

Per issue in map (excluding

exclude_issues

Validate milestone (project + group)
```
update_issue
```
with
```
milestone_id
```
One
```
set_issue_labels
```
—
```
remove_labels
```
+
```
add_labels
```
atomically (RF, Status, Equipe)
```
assign_issue
```
```
set_issue_estimate
```
from linked task header (seconds) only if
```
time_stats.time_estimate
```
is empty — never overwrite; skip values < 60

针对映射文件中的每个issue（排除

exclude_issues

列表中的项）：

验证里程碑（项目及组级别）
调用
```
update_issue
```
设置
```
milestone_id
```
单次调用原子操作
```
set_issue_labels
```
——同时执行
```
remove_labels
```
和
```
add_labels
```
（RF标签、状态标签、团队标签）
调用
```
assign_issue
```
分配经办人
仅当
```
time_stats.time_estimate
```
为空时，从关联任务标题中获取数据调用
```
set_issue_estimate
```
（单位：秒）——绝不覆盖已有值；跳过小于60秒的数值

Flow B — Per-task execution sync

流程B —— 单任务执行同步

Task start (before coding)

任务启动（编码前）

remove: status_backlog
add: status_in_progress

Record

START_TIME

START_EPOCH

when coding starts (for wall-clock

add_issue_spent_time

— see

../ns-execution-gitlab-issue/references/time-tracking.md

remove: status_backlog
add: status_in_progress

编码开始时记录

START_TIME

START_EPOCH

（用于计算实际耗时，调用

add_issue_spent_time

——详见

../ns-execution-gitlab-issue/references/time-tracking.md

）。

Task complete (after validation)

任务完成（验证后）

Only if already

status_in_progress

remove: status_in_progress
add: status_done, RF: NNN
add_issue_spent_time
add_issue_comment (internal=true)

Never backlog → done in one step.

仅当issue当前状态为

status_in_progress

时执行：

remove: status_in_progress
add: status_done, RF: NNN
add_issue_spent_time
add_issue_comment (internal=true)

禁止直接从待办状态（backlog）一步切换至完成状态（done）。

Anti-patterns

反模式

Wrong	Right
`assignee` on `update_issue`	`assign_issue`
Two label calls for one transition	Single atomic `set_issue_labels`
Manual `Milestone:` label	`milestone_id` on `update_issue`
`set_issue_estimate` for time spent	`add_issue_spent_time` with wall-clock duration
`set_issue_estimate` when estimate already set	Skip — preserve existing
Plan/ `estimate_seconds` as spent `duration`	Epoch delta only ( `time-tracking.md` )
Public comment for internal notes	`internal: true`

错误做法	正确做法
在 `update_issue` 中设置 `assignee`	调用 `assign_issue`
单次状态转换调用两次标签接口	调用单次原子操作 `set_issue_labels`
手动添加 `Milestone:` 标签	在 `update_issue` 中设置 `milestone_id`
使用 `set_issue_estimate` 记录已花费时间	调用 `add_issue_spent_time` 并传入实际耗时
已有预估时间时仍调用 `set_issue_estimate`	跳过——保留已有值
将规划/ `estimate_seconds` 作为已花费 `duration`	仅使用时间戳差值（详见 `time-tracking.md` ）
公开评论用于内部记录	设置 `internal: true`

References

参考资料

File	When
`references/gitlab-sync-config.template.md`	Bootstrap config
`mcp-gitlab-usage`	Tool schemas and gates

文件路径	使用场景
`references/gitlab-sync-config.template.md`	初始化配置
`mcp-gitlab-usage`	工具 schema 及权限控制