gitlab-issue

What this skill does

# 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 v