report-issue— agent skill

When to Use

Typical triggers:

• A git tool handler returns wrong results or throws on valid input
• A git provider (CliGitProvider) fails or misbehaves — wrong output parsing, error transformation, timeout handling
• Transport bugs — HTTP (Hono + Streamable HTTP), stdio, SSE framing, session handling
• Auth bugs — JWT / OAuth / scope enforcement
• Storage backend misbehaves — in-memory, filesystem, supabase, cloudflare
• Domain logic errors — wrong git output, missing edge cases, bad state transitions
• Resource handlers return stale, incomplete, or incorrect data
• Missing or incorrect .describe() on schema fields causing poor LLM tool use
• Feature requests — new git operations, verbosity levels, response fields, auth strategies, storage providers

For general gh CLI workflows outside issue filing (PRs, workflows, API access), see the github-cli skill.

Before Filing

1. Confirm the repo:

   gh repo view --json nameWithOwner -q '.nameWithOwner'

Should output cyanheads/git-mcp-server.

1. Search existing issues:

   gh issue list --search "your error message or keyword"

1. Reproduce the issue — confirm it's reproducible. Note the exact input, transport mode (stdio/http), git provider (cli), and any relevant env vars (GIT_SIGN_COMMITS, GIT_BASE_DIR, STORAGE_PROVIDER_TYPE, etc.).

1. Check logs — review server output and, if running HTTP, the response body for structured error details (McpError code + context).

1. Capture versions — bun pm ls @cyanheads/git-mcp-server, bun --version, git --version, OS version.

Writing Well-Structured Issues

Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).

• Lead with specifics. Name the tool, provider, resource, or symptom. "Currently git_merge throws McpError(INTERNAL_ERROR) on a CONFLICT exit instead of returning {conflicts: true}" beats "Merge is broken." A reader should know what's wrong before the end of the first sentence.
• Embed library/service links on first mention. [Hono](https://hono.dev/), [tsyringe](https://github.com/microsoft/tsyringe), [jose](https://github.com/panva/jose). Link to the canonical repo so readers can verify the dependency and reach docs in one click.
• Use `owner/repo#N` for cross-repo issue references. GitHub auto-renders them as linked references (e.g. cyanheads/mcp-ts-template#46). Bare #N only works for same-repo issues.
• Add a `Related: #N` line near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
• Lead design sections with a philosophy sentence. Bold a short principle before the tradeoff details — e.g. "Philosophy: conflicts are a structured success, not an error." Establishes the lens for the rest of the section.
• Prefer Markdown tables for comparisons. When showing options, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
• Separate `### Scope` from `### Out of scope`. The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
• Use `Depends on: owner/repo#N` to declare ordering explicitly when implementation is blocked on another issue landing first.
• Skip collaborator-framing sign-offs. Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.

Redact Before Posting

GitHub issues are public. Do not include secrets, credentials, API keys, JWT tokens, or git remote URLs that encode credentials. Redact sensitive values from env vars, headers, logs, and git URLs before submitting. Replace with obvious placeholders: REDACTED, sk-...REDACTED, https://[email protected]/.... Do not rely on partial masking — partial keys can still be exploited.

Filing a Bug

This repo does not currently ship .github/ISSUE_TEMPLATE/ YAML form templates, so use free-form titles and bodies. Structure the body with the sections below so the maintainer has everything needed to triage without asking.

CLI (non-interactive)

gh issue create \
  --title "bug(git_merge): conflicts thrown as McpError instead of structured success" \
  --label "bug" \
  --body "$(cat <<'ISSUE'
### Version

git-mcp-server v2.11.1

### Runtime

Bun 1.2.21 on macOS 15.x

### Transport

http (also reproduces on stdio)

### Git provider

cli (git 2.x)

### Description

`git_merge` currently throws `McpError(INTERNAL_ERROR)` when the merge exits non-zero due to a `CONFLICT` marker. Callers have to parse error messages and re-run `git_status` to recover state, even though `CONFLICT` is a documented success state.

### Steps to reproduce

1. Set up a repo with two divergent branches that touch the same line
2. `git_checkout { "branch": "main" }`
3. `git_merge { "branch": "feature" }` → throws instead of returning conflict info

### Actual behavior

McpError: INTERNAL_ERROR — git merge failed with exit code 1

### Expected behavior

{ "success": true, "conflicts": true, "conflictedFiles": ["path/to/file.ts"], "message": "Merge had conflicts — resolve and commit to finish" }

### Additional context

`git_rebase`, `git_cherry_pick`, `git_pull` share the same pattern and exhibit the same behavior.
ISSUE
)"

Browser (interactive)

gh issue create --web

Opens the standard GitHub issue form; use the body template above as a guide.

Title conventions

Format: type(scope): description

• type: bug, feat, docs, chore, perf, refactor
• scope: tool name (git_status, git_merge), subsystem (cli-provider, transport, auth, storage, config), or types

Examples:

• bug(git_commit): signing fails silently when gpg agent is unavailable
• feat(git_log): add --follow renames output flag
• docs(config): GIT_BASE_DIR interaction with session working dir is unclear
• perf(cli-provider): spawn overhead dominates short git_status calls

Labels

Combine labels: --label "bug" --label "regression".

Attaching logs or large output

bun run dev:stdio 2>&1 | head -200 > /tmp/git-mcp-error.log

# As part of a new issue
gh issue create \
  --title "bug(transport): stdio crashes on large diff payload" \
  --label "bug" \
  --body-file /tmp/git-mcp-error.log

# Or as a comment on an existing issue
gh issue comment <number> --body-file /tmp/git-mcp-error.log

For HTTP errors, capture the full JSON-RPC response (envelope + result.content[] or error) so the maintainer can see both the protocol frame and the tool error.

Filing a Feature Request

Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.

gh issue create \
  --title "feat(git_log): add follow-renames flag" \
  --label "enhancement" \
  --body "$(cat <<'ISSUE'
`git_log` currently does not expose `--follow`, so callers cannot trace the full history of a renamed file without falling back to raw `git log`. This is a common workflow when reviewing long-lived code paths.

Related: #N

## Proposal

Add `followRenames: boolean` to the `git_log` input schema. When `true` and exactly one `pathspec` is provided, thread `--follow` into the underlying git invocation. Default `false` to preserve current behavior.

### Proposed behavior

// Input schema addition followRenames: z .boolean() .default(false) .describe('Follow renames across the history. Requires exactly one pathspec.'),

Validation: if `followRenames: true` and `pathspec.length !== 1`, throw `McpError(INVALID_PARAMS)` with an actionable message.

### Scope

- `src/mcp-server/tools/definitions/git-log.tool.ts` — schema + logic
- `src/services/git/providers/cli/operations/commits/log.ts` — thread the flag into the `git log` argv
- README table entry for `git_log` updated if user-facing

### Out of scope

- Supporting `--follow` with zero or multiple pathspecs (git itself rejects it)
- Rewriting the output shape — same `GitLogResult` structure

### Alternatives considered

Auto-detect single-pathspec + enable `--follow` silently. Rejected: surprising default, and some callers deliberately want non-following history even with a single path.
ISSUE
)"

Following Up

# View issue details
gh issue view <number>

# Add context
gh issue comment <number> --body "Additional findings..."

# List your open issues
gh issue list --author @me

# Close if resolved
gh issue close <number> --reason completed --comment "Fixed in <commit or PR>"

Checklist

• [ ] Confirmed bug is in git-mcp-server, not an underlying git CLI issue
• [ ] Searched existing issues — no duplicate found
• [ ] All secrets, credentials, and tokens redacted (incl. git remote URLs)
• [ ] Issue filed with: version, runtime, transport, git provider, repro steps, actual vs expected behavior