gitlab-issue skill

---
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:

```markdown
## 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

```markdown
## 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

```markdown
## 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

```markdown
## 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"