Gitlab

GitLab CLI Skill

Execute GitLab helper functions and git commands with proper authentication.

You must source the helpers before use:

source ./_skills/connections/gitlab/gitlab/scripts/gitlab_helpers.sh

CLI Tips

NEVER USE RAW CURL OR DIRECT API CALLS

DO NOT write raw curl/HTTP requests like:

# ❌ WRONG - Never do this
curl -s --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" "${GITLAB_HOST}/api/v4/..."

ALWAYS use the provided helper functions:

# ✅ CORRECT - Use helper functions
gitlab_user                         # Get current user
gitlab_projects                     # List projects
gitlab_mr $PROJ MR_IID             # Get MR details

The helper functions handle authentication, error handling, and output formatting automatically.

CRITICAL: Project ID as First Parameter

ALL commands require explicit project_id as the FIRST parameter.

PROJ=$(gitlab_project_id "org/repo")  # Get project ID
gitlab_mr $PROJ 123                    # Use in commands

Code Review Helper Functions (GitLab)

Inline comment with suggestion block:

gitlab_create_diff_note $PROJ MR_IID "file.py" LINE 'Comment text

```suggestion:-0+2
fixed code line 1
fixed code line 2

' "LINE_TYPE"

- `LINE_TYPE`: "new" for added lines, "old" for removed
- Use single quotes to preserve backticks literally - NO escaping needed
- Offset notation `-X+Y`: remove X lines above, add Y lines below

**Discussion comment:**
```bash
gitlab_create_mr_discussion $PROJ MR_IID 'Comment text'

Suggestion Block Syntax (CRITICAL)

✅ CORRECT - Single quotes preserve backticks with offset notation:

gitlab_create_diff_note $PROJ 45 "src/app.py" 10 '🔴 CRITICAL: Issue

```suggestion:-0+1
if not input.strip():
    raise ValueError("Required")

' "new"

**❌ WRONG - Escaped backticks break rendering:**
```bash
gitlab_create_diff_note $PROJ 45 "src/app.py" 10 "\`\`\`suggestion:-0+1
code
\`\`\`" "new"

Key rules:

• Use single quotes to wrap comment body containing markdown
• Backticks inside single quotes are literal - write them normally
• NEVER escape backticks with backslashes (\`) - this breaks GitLab's markdown parser
• Triple backticks must include offset notation: ```suggestion:-X+Y
• Offset notation: -X (lines to remove above) +Y (lines to add below)

Essential Read Commands

MR info:

gitlab_mr $PROJ MR_IID                         # Get MR metadata
gitlab_mr_diff $PROJ MR_IID                    # Get full diff
gitlab_mr_diff $PROJ MR_IID --summary          # Get diff summary (fast)
gitlab_mr_diff $PROJ MR_IID --filter "\.py$"   # Filter by file pattern

List with filters:

gitlab_mrs $PROJ --state merged --author-username john
gitlab_issues $PROJ --state opened --assignee-username jane --labels "bug"
gitlab_pipelines $PROJ --status running --ref main

Other info:

gitlab_mr_commits $PROJ MR_IID                    # List MR commits
gitlab_mr_changes $PROJ MR_IID [per_page] [page]  # List changed files
gitlab_mr_discussions $PROJ MR_IID                 # List discussion threads
gitlab_mr_discussion $PROJ MR_IID DISCUSSION_ID   # Get specific thread
gitlab_mr_diff_metadata $PROJ MR_IID              # Get SHA refs for diff comments
gitlab_mr_approval_status $PROJ MR_IID            # Check merge readiness
gitlab_commits $PROJ [ref] [per_page] [page]      # List commits on branch
gitlab_branches $PROJ                              # List branches
gitlab_file $PROJ FILE_PATH [ref]                  # Get file content

CI/CD info:

gitlab_pipeline $PROJ PIPELINE_ID                  # Get pipeline details
gitlab_jobs $PROJ PIPELINE_ID                      # List pipeline jobs
gitlab_job_log $PROJ JOB_ID                        # Get job trace/log output
gitlab_pipeline_failures $PROJ PIPELINE_ID         # List failed jobs in pipeline
gitlab_job_failure_summary $PROJ JOB_ID            # Analyze job failure with log tail
gitlab_pipeline_history $PROJ [ref] [per_page]     # Recent pipelines on branch
gitlab_compare_pipelines $PROJ [ref]               # Compare latest failed vs successful
gitlab_ci_stats $PROJ [per_page]                   # Pipeline success/failure rates

Supported Parameters Reference

gitlab_mrs - List merge requests

Supported parameters:

• --state : opened | closed | merged | all (default: opened)
• --author-username : Filter by author username
• --assignee-username : Filter by assignee username
• --labels : Comma-separated labels (e.g., "bug,critical")
• --search : Keyword search in title/description
• --per-page : Results per page (default: 20, max: 100)

NOT SUPPORTED (will cause error):

• --created-after / --created-before - Date filtering not available
• --updated-after / --updated-before - Date filtering not available
• --milestone - Milestone filtering not supported
• Alternative: Use --search with date in text, or filter results post-fetch

Example:

# ✅ Correct
gitlab_mrs $PROJ --state merged --author-username john --per-page 50

# ❌ Wrong - unsupported flags
gitlab_mrs $PROJ --created-after "2026-01-01"  # ERROR: Unknown flag

gitlab_issues - List issues

Supported parameters:

• --state : opened | closed | all (default: opened)
• --assignee-username : Filter by username
• --labels : Comma-separated labels
• --search : Keyword search
• --per-page : Results per page

NOT SUPPORTED:

• --created-after / --created-before - Not available
• --milestone - Not supported
• --author - Use --search instead

gitlab_mr_diff - Get MR diff

Supported parameters:

• --summary : Show file paths and stats only (fast, recommended for large MRs)
• --filter PATTERN : Regex pattern to filter files (e.g., \.py$ for Python only)

NOT SUPPORTED:

• --context : Context lines not configurable
• --unified : Diff format not changeable

gitlab_mr_commits - List MR commits

Supported parameters:

• No additional flags supported (project_id and MR_IID only)

gitlab_pipelines - List pipelines

Supported parameters:

• --status : running | pending | success | failed | canceled | skipped
• --ref : Branch or tag name
• --per-page : Results per page

NOT SUPPORTED:

• --created-after / --created-before - Not available
• --user - Not supported

gitlab_branches - List branches

Supported parameters:

• project_id : Numeric project ID (required)

NOT SUPPORTED:

• --search : Not implemented
• --per-page : Not implemented
• --sort : Sorting not configurable
• --order : Ordering not available

gitlab_pipeline_history - Pipeline history for a branch

Positional parameters:

• project_id : Numeric project ID (required)
• ref : Branch/tag name (default: main)
• per_page : Results per page (default: 10)

gitlab_ci_stats - CI/CD success/failure rates

Positional parameters:

• project_id : Numeric project ID (required)
• per_page : Sample size of recent pipelines (default: 50)

gitlab_commits - List commits on a branch

Positional parameters:

• project_id : Numeric project ID (required)
• ref : Branch/tag name (default: main)
• per_page : Results per page (default: 20)
• page : Page number (default: 1)

gitlab_mr_changes - List changed files in an MR

Positional parameters:

• project_id : Numeric project ID (required)
• mr_iid : Merge request IID (required)
• per_page : Changes per page (default: 100)
• page : Page number (default: 1)
• all_pages : Fetch all pages, true/false (default: false)

Parameter Validation Rules

BEFORE executing any gitlab_ helper function:*

1. Check this SKILL.md - Verify the flag is listed in "Supported parameters"
2. If flag not listed - Assume it's unsupported, don't guess
3. If unsure - Use the basic command first, then check error message
4. Alternative approaches:
   • Post-fetch filtering: Get all results, filter in your script
   • Search text workarounds: Use --search with date/milestone text
   • Direct API: For very specific needs, consider raw GitLab API calls (not recommended)

Common mistake pattern:

# User asks: "List MRs from January 2026"
# ❌ WRONG: Assume date filtering exists
gitlab_mrs $PROJ --created-after "2026-01-01"  # Will fail

# ✅ CORRECT: Check SKILL.md first, then use supported approach
gitlab_mrs $PROJ --state all --per-page 100 | grep "2026-01"
# OR: Fetch recent MRs and filter by parsing JSON output

Essential Write Commands (Require Approval)

MR operations:

gitlab_update_mr $PROJ MR_IID --title "New Title" --description "Updated" --labels "ready"
gitlab_merge_mr $PROJ MR_IID       # Merge MR
gitlab_close_mr $PROJ MR_IID       # Close MR
gitlab_reopen_mr $PROJ MR_IID      # Reopen MR
gitlab_approve_mr $PROJ MR_IID     # Approve MR

Issue operations:

gitlab_create_issue $PROJ --title "Bug fix" --description "Details" --labels "bug,critical"
gitlab_update_issue $PROJ ISSUE_IID --title "New Title" --description "Updated" --labels "bug,feature"
gitlab_close_issue $PROJ ISSUE_IID        # Close issue
gitlab_reopen_issue $PROJ ISSUE_IID       # Reopen issue

Pipeline operations:

gitlab_trigger_pipeline $PROJ [ref]       # Trigger new pipeline (default ref: main)
gitlab_retry_pipeline $PROJ PIPELINE_ID   # Retry all failed jobs in pipeline
gitlab_cancel_pipeline $PROJ PIPELINE_ID  # Cancel running pipeline
gitlab_retry_job $PROJ JOB_ID            # Retry a specific failed job
gitlab_cancel_job $PROJ JOB_ID           # Cancel a specific running job
gitlab_play_job $PROJ JOB_ID             # Trigger a manual/gated job

MR/Issue comment operations:

gitlab_create_mr $PROJ SOURCE TARGET TITLE [DESC]           # Create merge request
gitlab_add_mr_comment $PROJ MR_IID BODY                     # Add comment to MR
gitlab_add_issue_comment $PROJ ISSUE_IID BODY                # Add comment to issue
gitlab_add_discussion_note $PROJ MR_IID DISCUSSION_ID BODY   # Reply to discussion thread
gitlab_update_discussion $PROJ MR_IID DISCUSSION_ID BODY     # Update first note in thread

Branch operations:

gitlab_create_branch $PROJ BRANCH_NAME [ref]  # Create branch (default ref: main)

CI/CD Pipelines

Workflow: Debug a failed pipeline

# 1. Find recent failed pipelines
gitlab_pipelines $PROJ --status failed --ref main

# 2. List failed jobs in that pipeline
gitlab_pipeline_failures $PROJ PIPELINE_ID

# 3. Get failure details and error log
gitlab_job_failure_summary $PROJ JOB_ID

# 4. Retry the failed job (or retry entire pipeline)
gitlab_retry_job $PROJ JOB_ID

Pipeline inspection (read):

Pipeline control (write — requires approval):

Key Rules

1. ALWAYS use helper functions for code review inline comments - Use gitlab_create_diff_note with offset notation
2. Always get project_id first - Use PROJ=$(gitlab_project_id "org/repo")
3. PROJECT_ID is first parameter - Every command needs it as first arg
4. Suggestion blocks require offset notation - Format: suggestion:-X+Y (X lines above, Y lines below)
5. Write operations: All require user approval
6. Multi-repo: Use variables:

   FRONTEND=$(gitlab_project_id "org/frontend")
   BACKEND=$(gitlab_project_id "org/backend")
   gitlab_mr $FRONTEND 45
   gitlab_mr $BACKEND 67
   

Errors

Critical Operations

⚠️ NEVER do these without explicit user instruction:

• gitlab_approve_mr - Only on explicit request
• gitlab_merge_mr - Only on explicit request
• gitlab_close_mr / gitlab_close_issue - Only on explicit request
• gitlab_delete_branch - Only on explicit request
• gitlab_trigger_pipeline - Triggers a new pipeline run
• gitlab_cancel_pipeline / gitlab_cancel_job - Interrupts running work
• gitlab_play_job - Triggers a manual/gated job
• gitlab_create_branch - Creates a branch

Output Format

Present results as a structured report:

Gitlab Report
═════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations