About gitlab-board-sync
gitlab-board-sync is a skill for mirroring local SDD planning and execution state to existing GitLab issues. It guides issue reads and carefully staged updates without creating issues.
Key features
- 01Read issue descriptions and comments
- 02Batch-update milestones, labels, assignees, estimates
- 03Sync task start and completion status
- 04Record spent time and internal notes
Use cases
- 01Review linked issues before implementation
- 02Apply planned work details to mapped issues
- 03Keep issue status aligned with task execution
MCP support
Requires a GitLab MCP server and directs tool calls through mcp-gitlab-usage. It uses GitLab issue-reading and update tools; it does not create issues.
Install
Copy the command and run it in a terminal.
npx skills add https:/ / github.com/ nextstage-brasil/ skills --skill gitlab-board-syncAfter installing, type/gitlab-board-syncin Claude Code to confirm it loaded.
Bundled filesevals/evals.jsonreferences/gitlab-sync-config.template.md
Details
From the project READMEGitLab Board Sync
Mirror local SDD planning/execution state onto existing GitLab issues. Does not create issues.
Prerequisites
- GitLab MCP available — follow
mcp-gitlab-usagefor all tool calls - If multiple GitLab MCP servers: ask human which to use
{product_root}/docs/context/gitlab-sync-config.mdvalidated- For post-planning batch:
gitlab-issue-feature-map.mdexists
Configuration
Read references/gitlab-sync-config.template.md for expected fields:
project_id,milestone_id,assignee_defaultstatus_backlog,status_in_progress,status_done,status_blockedrf_label_format,base_branch,work_branch,mr_target_branch
Discover unknown status labels via list_project_labels — confirm with human.
Flow C — Pre-implementation read
When task lists GitLab issue IIDs:
read_issuefor description + recent comments- Non-blocking if inaccessible — log warning, continue
- Do not mutate issue in this flow
Flow A — Post-planning batch
Per issue in map (excluding exclude_issues):
- Validate milestone (project + group)
update_issuewithmilestone_id- One
set_issue_labels—remove_labels+add_labelsatomically (RF, Status, Equipe) assign_issueset_issue_estimatefrom linked task header (seconds)
Flow B — Per-task execution sync
Task start (before coding)
remove: status_backlog
add: status_in_progress
Record start time for add_issue_spent_time.
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.
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 |
| Public comment for internal notes | internal: true |
References
| File | When |
|---|---|
references/gitlab-sync-config.template.md | Bootstrap config |
mcp-gitlab-usage | Tool schemas and gates |