mcpField
N
ns-gitlab-board-sync

ns-gitlab-board-sync

github.com/nextstage-brasil开发0611 次安装1 周前更新
代码仓库

关于 ns-gitlab-board-sync

面向 Claude Code 的技能，用于将本地 SDD 规划与执行状态同步到现有 GitLab issue。它区分读取、规划、任务和交付单元流程，并限制状态与工时更新方式。

主要功能

  1. 01读取 issue 描述和近期评论
  2. 02批量更新里程碑、标签和负责人
  3. 03同步任务及交付单元状态
  4. 04按实际耗时记录已用工时
  5. 05保留已有 issue 预估

适用场景

  1. 01编码前查看关联 issue
  2. 02为映射的 issue 批量应用规划信息
  3. 03随工作进展更新 issue 状态
  4. 04任务或交付单元完成后记录工时

MCP 相关

通过 GitLab MCP 工具读取和更新 issue、设置标签及负责人、管理预估、评论和工时。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nextstage-brasil/skills --skill ns-gitlab-board-sync

安装后在 Claude Code 中输入/ns-gitlab-board-sync确认已加载。

附带文件evals/evals.jsonreferences/gitlab-sync-config.template.md

详细介绍

GitLab 看板同步

将本地 SDD 规划／执行状态镜像到现有 GitLab issue。不会创建 issue。

前置条件

  1. GitLab MCP 可用——所有工具调用均遵循 mcp-gitlab-usage
  2. 如果有多个 GitLab MCP 服务：询问用户要使用哪一个
  3. 已验证 docs/context/gitlab-sync-config.md
  4. 对于规划后的批量处理：gitlab-issue-feature-map.md 已存在

配置

阅读 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 查找未知状态标签——与用户确认。

流程 C — 实施前读取

当任务列出 GitLab issue IID 时：

  1. 使用 read_issue 读取描述和近期评论
  2. 无法访问时不阻塞——记录警告并继续
  3. 此流程中不要修改 issue

流程 A — 规划后批量处理

对映射中的每个 issue（排除 exclude_issues）：

  1. 验证里程碑（项目 + 群组）
  2. 使用 milestone_id 执行 update_issue
  3. 执行一次 set_issue_labels——原子化地组合 remove_labels + add_labels（RF、Status、Equipe）
  4. 执行 assign_issue
  5. 仅当 time_stats.time_estimate 为空时，根据关联任务标题设置 set_issue_estimate（秒）——绝不覆盖；跳过小于 60 的值

流程 B — 按任务同步执行状态（旧版 1:1）

互斥规则：delivery-units.md 中存在任何 issue_iid 时 → 不要运行流程 B。所有者 = ../ns-spec-driven/references/delivery-units.md GitLab 状态／已用时间（SSoT）。

当任务行与其专属 GitLab issue 一一对应时（不存在交付单元文件，或单元尚未发布且使用旧版 gitlab-issue-feature-map.md）：

任务开始（编码前）
remove: status_backlog
add: status_in_progress

开始编码时记录 START_TIME / START_EPOCH，用于墙钟时间的 add_issue_spent_time（参见 ../ns-execution-gitlab-issue/references/time-tracking.md）。

任务完成（验证后）

仅当状态已为 status_in_progress 时：

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

绝不一步从 backlog 转为 done。

流程 D — 按交付单元

仅当 SSoT 行属于流程 D（已发布 issue_iid + 本地执行，无 G）时运行。当 G 管理生命周期时 → 跳过整个流程 D。

单元开始（单元任务编码前）
remove: status_backlog
add: status_in_progress

开始编码该单元时记录 START_TIME / START_EPOCH，用于单元级已用时间的墙钟计时。

单元完成（单元验证并获批准后）

仅当状态已为 status_in_progress 时：

remove: status_in_progress
add: status_done
add_issue_comment (internal=true)

仅限本地（SSoT 流程 D 行）：每个单元调用一次 add_issue_spent_time（墙钟时间，不是 estimate_sum）；将 spent_posted 设为 yes。

绝不一步从 backlog 转为 done。绝不在单元内按任务调用 add_issue_spent_time。当 G 管理同一 issue 时，绝不运行流程 D。

反面模式

错误正确做法
在 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仅使用 Epoch 时间差（time-tracking.md）
用公开评论记录内部备注设置 internal: true

参考资料

文件使用时机
references/gitlab-sync-config.template.md初始化配置
mcp-gitlab-usage工具架构和限制
../ns-spec-driven/references/delivery-units.mdGitLab 状态／已用时间（SSoT）

评论

支持 Markdown