Add comprehensive support for comment threads across all GitLab resources

Problem Statement

Currently, the plugin has limited support for replying to comment threads across GitLab resources. While some tools support basic commenting, the ability to reply to specific comments in threads, manage discussions, and maintain thread hierarchy is inconsistent or missing across different resource types.

Affected Resources

The following GitLab resources support threaded discussions but lack comprehensive tooling:

  1. Work Items (Issues, Tasks, Epics, etc.) - Partial support via gitlab_create_workitem_note
  2. Merge Requests - Has gitlab_create_mr_note but limited thread support
  3. Issues - Has gitlab_create_issue_note but no discussion management
  4. Epics - Has gitlab_create_epic_note but no thread functionality
  5. Commits - No comment thread support
  6. Snippets - No comment support at all

Use Cases

  1. Reply to specific feedback: "Answer the comment from Joe about the implementation approach"
  2. Thread-based discussions: "Comment on the thread about performance impact in MR !123"
  3. Contextual conversations: Maintain organized discussions by keeping related comments together
  4. Collaborative reviews: Enable team members to discuss specific points without cluttering the main comment stream
  5. Cross-resource discussions: Consistent threading experience across issues, MRs, epics, and work items
  6. Resolve discussions: Mark discussion threads as resolved after addressing feedback

Current State Analysis

Existing Tools with Partial Support:

  • gitlab_create_workitem_note - Supports discussion_id parameter
  • gitlab_create_mr_note - Creates notes but no thread management
  • gitlab_create_issue_note - Creates notes but no thread management
  • gitlab_create_epic_note - Creates notes but no thread management
  • gitlab_list_mr_discussions - Lists discussions but read-only
  • gitlab_list_mr_notes - Lists notes in flat structure
  • gitlab_list_issue_notes - Lists notes but no discussion grouping
  • gitlab_list_epic_notes - Lists notes but no discussion grouping
  • gitlab_get_workitem_notes - Lists notes with pagination

Missing Functionality:

  • No way to reply to specific discussion threads for most resources
  • No tools to resolve/unresolve discussions
  • No discussion management (create, update, delete threads)
  • Inconsistent API usage (some use REST, some use GraphQL)
  • Limited error handling for thread operations

Proposed Solution

Phase 1: Enhance Existing Comment Tools

Add thread support to existing note creation tools:

  1. gitlab_create_mr_note - Add discussion_id parameter for thread replies
  2. gitlab_create_issue_note - Add discussion_id parameter for thread replies
  3. gitlab_create_epic_note - Add discussion_id parameter for thread replies
  4. gitlab_create_workitem_note - Improve existing discussion_id handling
  5. Add validation and error handling for all thread operations

Phase 2: Add Discussion Management Tools

Create new tools for managing discussion threads:

  1. gitlab_get_mr_discussion - Get specific discussion thread with all replies
  2. gitlab_get_issue_discussion - Get specific discussion thread with all replies
  3. gitlab_get_epic_discussion - Get specific discussion thread with all replies
  4. gitlab_resolve_discussion - Mark discussion as resolved (MRs, commits)
  5. gitlab_unresolve_discussion - Reopen resolved discussion
  6. gitlab_create_discussion - Start new discussion thread with initial comment

Phase 3: Add Missing Comment Support

Add comment functionality for resources that lack it:

  1. gitlab_create_commit_note - Comment on commits with thread support
  2. gitlab_list_commit_discussions - List commit discussion threads
  3. gitlab_create_snippet_note - Comment on snippets
  4. gitlab_list_snippet_discussions - List snippet discussions

Phase 4: Unified Discussion API

Create a consistent interface across all resources:

  1. gitlab_reply_to_discussion - Universal tool for replying to any discussion
  2. gitlab_get_discussion - Universal tool for fetching discussion details
  3. Standardize discussion ID formats across REST and GraphQL APIs
  4. Provide helper functions to convert between ID formats

Phase 5: Testing & Documentation

  1. Test threaded replies across all resource types
  2. Verify thread hierarchy is preserved in GitLab UI
  3. Test discussion resolution workflows
  4. Create comprehensive documentation with examples for each resource type
  5. Add troubleshooting guide for common threading issues

Acceptance Criteria

Core Functionality

  • Users can reply to specific comments in threads for all supported resources
  • Thread hierarchy is preserved and displayed correctly in GitLab UI
  • Discussion resolution works for MRs and commits
  • Error handling provides clear feedback when thread operations fail

Resource Coverage

  • Work Items: Full thread support with discussion management
  • Merge Requests: Thread replies and resolution support
  • Issues: Thread replies and discussion management
  • Epics: Thread replies and discussion management
  • Commits: Comment and thread support added
  • Snippets: Comment and thread support added

Quality & Documentation

  • Consistent API across all resource types
  • Comprehensive documentation with examples for each resource
  • Tool descriptions clearly explain threading functionality
  • Error messages are helpful and actionable
  • Performance is acceptable for large discussion threads

Technical Notes

API Considerations

  • Work Items: Use GraphQL API, discussion ID format: gid://gitlab/Discussion/<id>
  • Merge Requests: Use REST API, discussion ID is numeric
  • Issues: Use REST API, discussion ID is string-based
  • Epics: Use REST API (Premium/Ultimate only)
  • Commits: Use REST API, supports line-specific comments
  • Snippets: Use REST API

Implementation Details

  • Need to handle both REST and GraphQL APIs
  • Discussion IDs have different formats across APIs
  • Some resources require project context, others require group context
  • Rate limiting and API quotas must be considered
  • Thread depth limits may vary by resource type

Breaking Changes

  • Existing tools will have new optional parameters (backward compatible)
  • New tools follow consistent naming convention: gitlab_<action>_<resource>_<object>

Priority Breakdown

High Priority (Most commonly used):

  • Merge Request thread replies and resolution
  • Issue thread replies
  • Work Item thread improvements

Medium Priority:

  • Epic thread replies
  • Commit comments
  • Discussion management tools

Low Priority:

  • Snippet comments
  • Unified discussion API

Additional Context

This feature would significantly improve collaboration by providing consistent, organized discussion capabilities across all GitLab resources. Users expect threading to work similarly whether they're commenting on an MR, issue, epic, or work item.

Related Issues

  • Original scope was limited to work items only
  • Expanding to cover all GitLab resources with discussion support
  • Aligns with GitLab's unified approach to discussions across the platform
Edited by Vladimir Glafirov