Skip to content

cloudthinker-ai/CloudSkills / skills/connections/gitlab

REQUIRED helper functions (never raw curl), project_id patterns, suggestion block syntax with offset notation

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

CommandPurpose
gitlab_pipeline $PROJ PIDGet pipeline details (status, ref, SHA)
gitlab_jobs $PROJ PIDList all jobs in a pipeline
gitlab_job_log $PROJ JOB_IDGet job trace/log output
gitlab_pipeline_failures $PROJ PIDList only failed jobs with failure reasons
gitlab_job_failure_summary $PROJ JOB_IDJob metadata + last 50 lines of log
gitlab_pipeline_history $PROJ [ref] [per_page]Recent pipelines on a branch
gitlab_compare_pipelines $PROJ [ref]Compare latest failed vs last successful
gitlab_ci_stats $PROJ [per_page]Success/failure rates over recent pipelines

Pipeline control (write — requires approval):

CommandPurpose
gitlab_trigger_pipeline $PROJ [ref]Trigger a new pipeline run
gitlab_retry_pipeline $PROJ PIDRetry all failed jobs in pipeline
gitlab_cancel_pipeline $PROJ PIDCancel a running pipeline
gitlab_retry_job $PROJ JOB_IDRetry a specific failed job
gitlab_cancel_job $PROJ JOB_IDCancel a specific running job
gitlab_play_job $PROJ JOB_IDTrigger a manual/gated job

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

ProblemSolution
"project not found"Use gitlab_project_id "org/repo" to get correct ID
"line not in diff"Use gitlab_create_mr_discussion instead
"authentication failed"Token auto-configured, verify project is accessible
Response too largeUse summary mode: gitlab_mr_diff $PROJ MR --summary
"job not retryable"Check job status with gitlab_jobs first — only failed jobs can be retried
"pipeline not found"Use gitlab_pipelines to list correct pipeline IDs

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

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"Follow the full discovery → analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"Try the command and report the actual errorAssumed permission failures prevent useful investigation; actual errors are informative
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall