gitlab-issues

GitLab Issues Integration

Manage GitLab issues using bash scripts. Create issues, create sub-issues, list issues, read comments, post updates, assign people, and create merge requests from issues.

How to Use

Call bash scripts directly via the Bash tool. No MCP server required.

Scripts location: ~/.claude/plugins/cache/awesome-agent-toolkit/gitlab-issues/1.2.1/core/scripts/

IMPORTANT: Environment variables must be set. Check with:

echo $GITLAB_HOST_URL $GITLAB_TOKEN $GITLAB_PROJECT_ID

If empty, add them to ~/.claude/settings.json under env:

{
  "env": {
    "GITLAB_HOST_URL": "https://gitlab.com",
    "GITLAB_TOKEN": "glpat-xxxxxxxxxxxx",
    "GITLAB_PROJECT_ID": "12345678"
  }
}

Available Commands

Set PLUGIN_DIR=~/.claude/plugins/cache/awesome-agent-toolkit/gitlab-issues/1.2.1

Create Issue

# Create a simple issue (title only)
bash $PLUGIN_DIR/core/scripts/create-issue.sh '{"title": "Fix login bug"}'

# Create issue with description and labels
bash $PLUGIN_DIR/core/scripts/create-issue.sh '{"title": "Add dark mode", "description": "Implement dark mode toggle in settings", "labels": "feature,ui"}'

# Create issue with full details
bash $PLUGIN_DIR/core/scripts/create-issue.sh '{"title": "API rate limiting", "description": "Add rate limiting to public endpoints", "labels": "backend,security", "assignee_ids": [12], "milestone_id": 8, "due_date": "2025-03-01", "weight": 3}'

# Create a confidential issue
bash $PLUGIN_DIR/core/scripts/create-issue.sh '{"title": "Security vulnerability", "description": "Details...", "confidential": true}'

Returns created issue details including IID, URL, assignees, and labels.

Create Sub-Issue (Child Issue)

# Create a sub-issue linked to parent issue #45
bash $PLUGIN_DIR/core/scripts/create-sub-issue.sh 45 '{"title": "Implement login form validation"}'

# Create sub-issue with description and labels
bash $PLUGIN_DIR/core/scripts/create-sub-issue.sh 45 '{"title": "Add unit tests for auth", "description": "Cover edge cases", "labels": "testing"}'

# Create sub-issue with assignee
bash $PLUGIN_DIR/core/scripts/create-sub-issue.sh 45 '{"title": "Update API docs", "assignee_ids": [15], "labels": "docs"}'

Creates a new issue and links it as a child of the parent issue. On GitLab Premium 16.0+ uses native parent/child hierarchy; otherwise falls back to a "relates_to" link.

List Issues

# List open issues (default)
bash $PLUGIN_DIR/core/scripts/list-issues.sh

# List closed issues
bash $PLUGIN_DIR/core/scripts/list-issues.sh closed

# List all issues
bash $PLUGIN_DIR/core/scripts/list-issues.sh all

# List issues from a specific milestone
bash $PLUGIN_DIR/core/scripts/list-issues.sh opened "Sprint 23"

Get Issue Details

bash $PLUGIN_DIR/core/scripts/get-issue-details.sh 45

Returns full issue details including description, assignees, labels, milestone.

Get Issue Comments

bash $PLUGIN_DIR/core/scripts/get-issue-comments.sh 45

Post Comment on Issue

bash $PLUGIN_DIR/core/scripts/post-issue-comment.sh 45 "Your comment here"

Update Issue

# Update description
bash $PLUGIN_DIR/core/scripts/update-issue.sh 45 --description "New description"

# Assign users (by user ID)
bash $PLUGIN_DIR/core/scripts/update-issue.sh 45 --assignee-ids "12,15"

# Set milestone (by milestone ID)
bash $PLUGIN_DIR/core/scripts/update-issue.sh 45 --milestone-id 8

# Add labels
bash $PLUGIN_DIR/core/scripts/update-issue.sh 45 --labels "bug,urgent"

# Close issue
bash $PLUGIN_DIR/core/scripts/update-issue.sh 45 --state-event close

List Milestones

bash $PLUGIN_DIR/core/scripts/list-milestones.sh

Use this to find milestone IDs for filtering or assigning.

List Project Members

bash $PLUGIN_DIR/core/scripts/list-project-members.sh

Use this to find user IDs for assigning issues.

Create MR from Issue

bash $PLUGIN_DIR/core/scripts/create-mr-from-issue.sh 45 feature/my-branch

Creates a merge request linked to the issue. Merging will auto-close the issue.

Workflows

1. List Issues from Milestone

When user asks "show issues in Sprint 23":

1. Run: bash $PLUGIN_DIR/core/scripts/list-milestones.sh to find milestone
2. Run: bash $PLUGIN_DIR/core/scripts/list-issues.sh opened "Sprint 23"
3. Present as table with IID, title, assignees, labels

2. Get Issue and Post Update

When user asks about a specific issue:

1. Run: bash $PLUGIN_DIR/core/scripts/get-issue-details.sh <iid>
2. Display description and metadata
3. If user wants to comment: bash $PLUGIN_DIR/core/scripts/post-issue-comment.sh <iid> "comment"

3. Assign Issue to Team Member

When user asks to assign an issue:

1. Run: bash $PLUGIN_DIR/core/scripts/list-project-members.sh to find user ID
2. Run: bash $PLUGIN_DIR/core/scripts/update-issue.sh <iid> --assignee-ids "<user_id>"

4. Create Issue with Assignment

When user asks to create and assign an issue:

1. Run: bash $PLUGIN_DIR/core/scripts/list-project-members.sh to find user ID
2. Run: bash $PLUGIN_DIR/core/scripts/list-milestones.sh to find milestone ID (if needed)
3. Run: bash $PLUGIN_DIR/core/scripts/create-issue.sh '{"title": "...", "assignee_ids": [<user_id>], "milestone_id": <milestone_id>}'

5. Break Down Issue into Sub-Issues

When user asks to split an issue into tasks:

1. Run: bash $PLUGIN_DIR/core/scripts/get-issue-details.sh <parent_iid> to understand the parent
2. For each sub-task, run: bash $PLUGIN_DIR/core/scripts/create-sub-issue.sh <parent_iid> '{"title": "Sub-task title", "description": "..."}'
3. Verify with: bash $PLUGIN_DIR/core/scripts/get-issue-details.sh <parent_iid> to see linked issues

Output Format

Present issues as a table:

IID	Title	State	Assignees	Labels	Milestone
#45	Fix login timeout	opened	@alice	bug, urgent	Sprint 23