repo-github-issues

# GitHub Issues Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server. ## Available MCP Tools | Tool | Purpose | |------|---------| | `mcp__github__create_issue` | Create new issues | | `mcp__github__update_issue` | Update existing issues | | `mcp__github__get_issue` | Fetch issue details | | `mcp__github__search_issues` | Search issues | | `mcp__github__add_issue_comment` | Add comments | | `mcp__github__list_issues` | List repository issues | | `mcp__github__sub_issue_write` | Add, remove, or reprioritise a sub-issue (`sub_issue_id` is the numeric GitHub issue **id**, not the `#` number) | ## Workflow 1. **Determine action**: Create, update, or query? 2. **Gather context**: Get repo info, existing labels, milestones if needed 3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md) - These markdown templates mirror the YAML issue forms in `.github/ISSUE_TEMPLATE/` - YAML templates are canonical structure (used by humans via GitHub UI) - Markdown templates are for AI programmatic creation (via MCP tools) - See [references/TEMPLATE_SYNC.md](references/TEMPLATE_SYNC.md) for synchronisation governance 4. **Execute**: Call the appropriate MCP tool 5. **Confirm**: Report the issue URL to user For SoloDevBoard, labels must follow `plan/LABEL_STRATEGY.md` using `type/`, `priority/`, `status/`, `area/`, and optionally `size/`. ## Creating Issues ### Required Parameters ``` owner: repository owner (org or user) repo: repository name title: clear, actionable title body: structured markdown content ``` ### Optional Parameters ``` labels: ["type/bug", "priority/medium", "status/todo", "area/dashboard", ...] assignees: ["username1", "username2"] milestone: milestone number (integer) ``` ### Title Guidelines - Start with type prefix when useful: `[Bug]`, `[Feature]`, `[Docs]` - Be specific and actionable - Keep under 72 characters - Examples: - `[Bug] Login fails with SSO enabled` - `[Feature] Add dark mode support` - `Add unit tests for auth module` ### Body Structure Always use the templates in [references/templates.md](references/templates.md). Choose based on issue type: | User Request | Template | YAML Form Mirror | |--------------|----------|------------------| | Bug, error, broken, not working | Bug Report | `.github/ISSUE_TEMPLATE/bug.yml` | | Feature, enhancement, add, new | Feature / User Story | `.github/ISSUE_TEMPLATE/feature.yml` | | Task, chore, refactor, update | Chore / Technical Debt | `.github/ISSUE_TEMPLATE/chore.yml` | **Note:** Markdown templates mirror YAML issue forms which humans use via GitHub UI. They must stay synchronised — see [references/TEMPLATE_SYNC.md](references/TEMPLATE_SYNC.md). ## Updating Issues Use `mcp__github__update_issue` with: ``` owner, repo, issue_number (required) title, body, state, labels, assignees, milestone (optional - only changed fields) ``` State values: `open`, `closed` ## Examples ### Example 1: Bug Report **User**: "Create a bug issue - the login page crashes when using SSO" **Action**: Call `mcp__github__create_issue` with: ```json { "owner": "github", "repo": "awesome-copilot", "title": "[Bug] Login page crashes when using SSO", "body": "## Description\nThe login page crashes when users attempt to authenticate using SSO.\n\n## Steps to Reproduce\n1. Navigate to login page\n2. Click 'Sign in with SSO'\n3. Page crashes\n\n## Expected Behaviour\nSSO authentication should complete and redirect to dashboard.\n\n## Actual Behaviour\nPage becomes unresponsive and displays error.\n\n## Environment\n- Browser: [To be filled]\n- OS: [To be filled]\n\n## Additional Context\nReported by user.", "labels": ["bug"] } ``` ### Example 2: Feature Request **User**: "Create a feature request for dark mode with high priority" **Action**: Call `mcp__github__create_issue` with: ```json { "owner": "github", "repo": "awesome-copilot", "title": "[Feature] Add dark mode support", "body": "## Summary\nAdd dark mode theme option for improved user experience and accessibility.\n\n## Motivation\n- Reduces eye strain in low-light environments\n- Increasingly expected by users\n- Improves accessibility\n\n## Proposed Solution\nImplement theme toggle with system preference detection.\n\n## Acceptance Criteria\n- [ ] Toggle switch in settings\n- [ ] Persists user preference\n- [ ] Respects system preference by default\n- [ ] All UI components support both themes\n\n## Alternatives Considered\nNone specified.\n\n## Additional Context\nHigh priority request.", "labels": ["enhancement", "high-priority"] } ``` ## SoloDevBoard Label Rules Always apply at least one `type/` and one `priority/` label. | Group | Examples | |-------|----------| | `type/` | `type/epic`, `type/feature`, `type/story`, `type/enabler`, `type/test`, `type/bug`, `type/chore`, `type/documentation` | | `priority/` | `priority/critical`, `priority/high`, `priority/medium`, `priority/low` | | `status/` | `status/todo`, `status/in-progress`, `status/blocked`, `status/ice-box`, `status/in-review`, `status/done` | | `area/` | `area/dashboard`, `area/repositories`, `area/migration`, `area/labels`, `area/board-rules`, `area/triage`, `area/actions-templates`, `area/planning`, `area/infrastructure`, `area/docs` | Use `area/repositories` for the Repositories catalogue (`/repositories`), not `area/dashboard`. Use `area/planning` for Planning (`/planning`), not `area/dashboard`. Use `area/actions-templates` for Actions Templates (`/actions-templates`). See `plan/LABEL_STRATEGY.md` for the full `area/` guidance. `area/*` labels are for this repository's triage only; they are not exported via Label Manager's recommended catalogue ([#446](https://github.com/markheydon/solo-dev-board/issues/446)). | `size/` | `size/xs`, `size/s`, `size/m`, `size/l`, `size/xl` | ## Issue relationships (agents must set these) After creating a planned hierarchy, **do not** ask the user to click Sub-issues or Relationships in the GitHub UI. 1. **Parent / child:** GitHub MCP `sub_issue_write` with `method: add`, parent `issue_number`, and child `sub_issue_id` (database id from create/get). To move a child, use `replace_parent: true`. 2. **Blocking:** REST via `gh api` as documented in `repo-github-gh-cli` (`POST .../issues/{blocked_number}/dependencies/blocked_by` with JSON integer `issue_id` of the **blocking** issue). `gh issue` has no first-class block command yet ([cli/cli#10298](https://github.com/cli/cli/issues/10298)). 3. Mention `#N` in the issue body as well so the graph is readable without opening the Relationships widget. If either API returns an error other than “already taken”, put a **Manual fallback** table in the planning handoff with the exact `gh api` commands. ## Tips - Always confirm the repository context before creating issues - Ask for missing critical information rather than guessing - Link related issues when known: `Related to #123` - For updates, fetch current issue first to preserve unchanged fields