name: GitLab Issue
description: Creates, retrieves, updates, and manages GitLab issues with comprehensive context gathering. Use when the user wants to create a new issue, view issue details, update existing issues, list project issues, or manage issue workflows in GitLab.
allowed-tools: gitlab-mcp(create_issue), gitlab-mcp(get_issue), gitlab-mcp(list_issues), gitlab-mcp(update_issue), gitlab-mcp(get_project), gitlab-mcp(list_merge_requests)
license: MIT
metadata:
author: Foundation Skills
version: 1.0.0
mcp-server: gitlab-mcp

GitLab Issue Management

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

GitLab Instance Configuration

This skill is configured for a self-hosted GitLab instance:
- GitLab URL: https://gitlab-erp-pas.dedalus.lan
- All project identifiers, URLs, and references should use this self-hosted instance
- Ensure you have appropriate access credentials configured for this GitLab server

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:

Self-hosted GitLab Instance: https://gitlab-erp-pas.dedalus.lan

Use gitlab-mcp(get_project) to:
- Confirm project exists on the self-hosted GitLab instance
- Get project details (default branch, visibility, etc.)
- Understand project structure
- Verify project path format (e.g., "namespace/project")

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

• Self-hosted GitLab: All operations use https://gitlab-erp-pas.dedalus.lan
• Always verify project access - Ensure you have permission to create/modify issues on the self-hosted instance
• 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"