GitLab Issue

GitLab Issue Management

Create, retrieve, update, and manage GitLab issues with comprehensive context integration and structured workflows.

When to Use This Skill

Activate this skill when:

• The user wants to create a new GitLab issue
• The user asks to view or retrieve issue details
• The user needs to update an existing issue
• The user wants to list issues in a project
• The user mentions managing issues, tickets, or tasks in GitLab
• The user wants to close, reopen, or modify issue properties
• The user needs to link issues to merge requests

Critical Rules

IMPORTANT: Always confirm project_id before creating or modifying issues

Always use descriptive issue titles and provide structured descriptions

Never create duplicate issues - search existing issues first when appropriate

Workflow

1. Gather Context

First, collect information about the current project and context:

• Identify the project (project_id or URL-encoded path)
• Understand the type of issue (bug, feature, task, etc.)
• Gather relevant labels, milestones, and assignees if applicable

2. Project Verification

Before any operation, verify the project exists and you have the correct identifier:

Use gitlab-mcp(get_project) to:

• Confirm project exists
• Get project details (default branch, visibility, etc.)
• Understand project structure

3. Issue Operations

Creating a New Issue

When creating issues, gather complete context:

Required Information:

• project_id: Project identifier (e.g., "namespace/project" or numeric ID)
• title: Clear, descriptive issue title

Optional but Recommended:

• description: Detailed description in Markdown format
• labels: Array of label names (e.g., ["bug", "priority::high"])
• assignee_ids: Array of user IDs to assign
• milestone_id: Milestone ID to associate
• due_date: Due date in YYYY-MM-DD format
• confidential: Boolean for sensitive issues

Human-in-the-Loop - Ask for Context

Always use AskUserQuestion to clarify issue details:

Question: "What type of issue is this?"
Options:
- "Bug report - something is not working correctly"
- "Feature request - new functionality needed"
- "Task - work item to complete"
- "Documentation - documentation needs update"
- "Other - let me describe it"

Issue Description Template:

Structure descriptions for clarity:

## Summary
[Brief description of the issue]

## Current Behavior
[What is happening now - for bugs]

## Expected Behavior
[What should happen - for bugs]

## Steps to Reproduce
[For bugs - numbered steps]

## Acceptance Criteria
[For features/tasks - what defines "done"]

## Additional Context
[Screenshots, logs, related issues, etc.]

Retrieving Issue Details

Use gitlab-mcp(get_issue) with:

• project_id: Project identifier
• issue_iid: Internal issue ID (the number shown in GitLab, e.g., #42)

This returns complete issue information including:

• Title and description
• State (opened/closed)
• Labels and milestone
• Assignees and author
• Created/updated timestamps
• Related merge requests

Listing Issues

Use gitlab-mcp(list_issues) with filters:

• project_id: Project identifier
• state: "opened", "closed", or "all"
• labels: Filter by labels
• milestone: Filter by milestone title
• assignee_id: Filter by assignee
• search: Search in title and description
• order_by: Sort by "created_at", "updated_at", "priority", etc.
• sort: "asc" or "desc"
• per_page: Results per page (max 100)

Updating an Issue

When updating issues, only provide changed fields:

Use gitlab-mcp(update_issue) with:

• project_id: Project identifier
• issue_iid: Internal issue ID
• Plus any fields to update (title, description, labels, state_event, etc.)

State Changes:

• state_event: "close" - Close the issue
• state_event: "reopen" - Reopen the issue

4. Linking to Merge Requests

To find related merge requests:

Use gitlab-mcp(list_merge_requests) with filters to find MRs that reference the issue:

• Search for issue number in MR titles/descriptions
• Check MR descriptions for "Closes #XX" or "Fixes #XX" patterns

5. Execute Operations (Requires Confirmation)

CRITICAL: Confirm with user before creating or modifying issues

After gathering all information, present a summary for user approval:

Creating issue in project: namespace/project
Title: [title]
Description: [summary]
Labels: [labels]
Assignee: [assignee]

Proceed with issue creation?

Issue Type Templates

Bug Report

## Bug Description
[Clear description of the bug]

## Environment
- Version: [version]
- OS: [operating system]
- Browser: [if applicable]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [See error]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Screenshots/Logs
[Attach relevant files]

## Possible Solution
[Optional: if you have ideas]

Feature Request

## Feature Description
[Clear description of the requested feature]

## Problem Statement
[What problem does this solve?]

## Proposed Solution
[How should this work?]

## Alternatives Considered
[Other approaches considered]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Additional Context
[Mockups, examples, etc.]

Task

## Task Description
[What needs to be done]

## Background
[Why is this needed?]

## Requirements
- [ ] [Requirement 1]
- [ ] [Requirement 2]

## Definition of Done
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Dependencies
[Related issues, blockers]

Examples

Example 1: Creating a Bug Report

User: "Create an issue for the login bug we discussed"

AI Workflow:

1. Ask for project_id if not known
2. Ask clarifying questions about the bug
3. Generate structured description
4. Present summary for confirmation
5. Create issue with gitlab-mcp(create_issue)

Result:

Title: [BUG] Login fails with OAuth2 when session expires

Description:
## Bug Description
Users are unable to log in using OAuth2 authentication when their 
previous session has expired.

## Steps to Reproduce
1. Log in with OAuth2 (Google/GitHub)
2. Wait for session to expire (or clear cookies)
3. Attempt to log in again
4. Observe error: "Invalid state parameter"

## Expected Behavior
User should be redirected to OAuth provider and log in successfully.

## Actual Behavior
Login fails with "Invalid state parameter" error.

## Environment
- Version: 2.3.1
- Browser: Chrome 120, Firefox 121

Labels: ["bug", "priority::high", "auth"]

Example 2: Listing and Filtering Issues

User: "Show me all open bugs assigned to me"

AI Workflow:

1. Use gitlab-mcp(list_issues) with filters:
   • state: "opened"
   • labels: ["bug"]
   • scope: "assigned_to_me"

Result:

Found 3 open bug issues assigned to you:

#142 - [BUG] API timeout on large file uploads
      Labels: bug, priority::medium
      Created: 2024-01-15

#138 - [BUG] Dashboard graphs not rendering on Safari
      Labels: bug, frontend, priority::low
      Created: 2024-01-12

#125 - [BUG] Email notifications delayed by 30+ minutes
      Labels: bug, priority::high
      Created: 2024-01-08

Example 3: Updating an Issue

User: "Close issue #142 and add a comment that it's fixed in v2.4.0"

AI Workflow:

1. First, add a note/comment to the issue
2. Then update issue state to closed

Using gitlab-mcp(update_issue):

project_id: "mygroup/myproject"
issue_iid: 142
state_event: "close"

Result:

Issue #142 "[BUG] API timeout on large file uploads" has been closed.

Example 4: Feature Request with Full Context

User: "Create a feature request for adding dark mode support"

AI Workflow:

1. Ask clarifying questions about the feature
2. Gather acceptance criteria
3. Create structured issue

Result:

Title: [FEATURE] Add dark mode theme support

Description:
## Feature Description
Implement a dark mode theme option that users can toggle in their 
preferences.

## Problem Statement
Users working in low-light environments experience eye strain with 
the current bright interface. Dark mode would improve accessibility 
and user comfort.

## Proposed Solution
- Add theme toggle in user preferences
- Implement CSS variables for theme colors
- Store preference in user settings
- Support system preference detection

## Acceptance Criteria
- [ ] User can toggle between light/dark mode in settings
- [ ] Theme preference persists across sessions
- [ ] System preference is detected on first visit
- [ ] All UI components support both themes
- [ ] No accessibility contrast issues in dark mode

## Additional Context
Reference designs: [link to mockups]
Similar implementations: GitHub, GitLab, VS Code

Labels: ["feature", "enhancement", "ux"]

Important Notes

• Always verify project access - Ensure you have permission to create/modify issues
• Use labels consistently - Follow project labeling conventions
• Be specific in titles - Prefix with [BUG], [FEATURE], [TASK] for clarity
• Include reproduction steps - Essential for bug reports
• Define acceptance criteria - Clear "definition of done" for features/tasks
• Link related issues - Use "Related to #XX" or "Blocks #XX" in descriptions
• Mention users with @username - For visibility and notifications
• Use milestones - Associate issues with releases or sprints when applicable

GitLab Issue Best Practices

Writing Effective Titles

• Be concise but descriptive
• Include issue type prefix: [BUG], [FEATURE], [TASK], [DOCS]
• Mention affected component if applicable
• Avoid vague titles like "Fix bug" or "Update code"

Structuring Descriptions

• Use Markdown formatting for readability
• Include all relevant context upfront
• Add screenshots or logs when helpful
• Link to related issues, MRs, or documentation
• Use task lists for trackable sub-items

Label Strategy

• Use scoped labels (e.g., priority::high, status::in-progress)
• Combine type labels (bug, feature) with area labels (frontend, api)
• Keep label taxonomy consistent across projects

Assignment and Workflow

• Assign issues to specific team members
• Use milestones for sprint/release planning
• Update issue status as work progresses
• Close issues with reference to fixing MR: "Closes #XX"