gitlab-issue

---
name: "gitlab-issue"
description: "Crée, récupère, met à jour et gère les issues GitLab avec collecte complète du contexte. À utiliser quand l'utilisateur veut créer une nouvelle issue, voir les détails d'une issue, mettre à jour des issues existantes, lister les issues du projet ou gérer les workflows d'issues sur GitLab (glab CLI). Si l'utilisateur ne précise pas la plateforme, se référer au remote git du dépôt : utiliser ce skill uniquement si le remote est GitLab — sinon voir github-issues."
license: "MIT"
---

# GitLab Issue Management

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

## Prerequisites

- **glab** (GitLab CLI): required for all issue operations — install from https://gitlab.com/gitlab-org/cli or `brew install glab`

## 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 `glab repo view` 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 `glab issue view <iid>` with:
- `<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 `glab issue list` with filters:
- `--state`: "opened", "closed", or "all"
- `--label`: Filter by labels
- `--milestone`: Filter by milestone title
- `--assignee`: 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 `glab issue update <iid>` with the relevant flags for fields to change (title, description, labels, etc.)

**State Changes:**
- `glab issue close <iid>` - Close the issue
- `glab issue reopen <iid>` - Reopen the issue

### 4. Linking to Merge Requests

To find related merge requests:

Use `glab mr list` 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 `glab issue create --title "<title>" --description "<description>" --label "bug,priority::high,auth"`

**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 `glab issue list --state opened --label bug --assignee @me` to list matching issues

**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: `glab issue note 142 --message "Fixed in v2.4.0. Closing this issue."`
2. Then close the issue: `glab issue close 142`

**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"