glab

# GitLab CLI (glab) Skill

Provides guidance for using `glab`, the official GitLab CLI, to perform GitLab operations from the terminal.

## When to Use This Skill

Invoke when the user needs to:
- Create, review, or manage merge requests
- Work with GitLab issues
- Monitor or trigger CI/CD pipelines
- Clone or manage repositories
- Perform any GitLab operation from the command line

## Prerequisites

Verify glab installation before executing commands:
```bash
glab --version
```

If not installed, inform the user and provide platform-specific installation guidance.

## Authentication Quick Start

Most glab operations require authentication:

```bash
# Interactive authentication
glab auth login

# Check authentication status
glab auth status

# For self-hosted GitLab
glab auth login --hostname gitlab.example.org

# Using environment variables
export GITLAB_TOKEN=your-token
export GITLAB_HOST=gitlab.example.org  # for self-hosted
```

## Core Workflows

### Creating a Merge Request

```bash
# 1. Ensure branch is pushed
git push -u origin feature-branch

# 2. Create MR
glab mr create --title "Add feature" --description "Implements X"

# With reviewers and labels
glab mr create --title "Fix bug" --reviewer=alice,bob --label="bug,urgent"
```

### Reviewing Merge Requests

```bash
# 1. List MRs awaiting your review
glab mr list --reviewer=@me

# 2. Checkout MR locally to test
glab mr checkout <mr-number>

# 3. After testing, approve
glab mr approve <mr-number>

# 4. Add a general comment
glab mr note <mr-number> -m "Please update tests"
```

#### Posting Inline DiffNote Comments

To anchor a comment to a specific line in the diff (a `DiffNote`), you **must** use a JSON body with the `Content-Type: application/json` header. Using `-F` form fields will create an unanchored `DiscussionNote`.

```bash
# Get SHA values from the MR
glab mr view <id> --output=json | grep -oP '"(base_sha|head_sha|start_sha)":\s*"\K[0-9a-f]{40}'

# Post a DiffNote on a new line
glab api --method POST "projects/:id/merge_requests/:iid/discussions" \
  -H "Content-Type: application/json" \
  --input - <<'JSONEOF'
{
  "body": "Your review comment here",
  "position": {
    "base_sha": "<base_sha>",
    "start_sha": "<start_sha>",
    "head_sha": "<head_sha>",
    "position_type": "text",
    "new_path": "path/to/file.js",
    "new_line": 42
  }
}
JSONEOF
```

**Key rules for DiffNotes:**
- Always use `--input -` with a heredoc and `-H "Content-Type: application/json"`. Never use `-F` for the `position` object — it will silently create a `DiscussionNote` instead.
- Line numbers are **new file line numbers** calculated from the diff hunk headers (`@@ -old,count +new,count @@`), not the diff output line numbers. Count only context lines and `+` lines from the hunk start.
- Verify findings on the **MR source branch** (`git fetch origin <branch>` then `git grep`), not the current working branch.
- To update an existing note: `glab api --method PUT "projects/:id/merge_requests/:iid/notes/:note_id" -H "Content-Type: application/json" --input - <<< '{"body":"updated text"}'`
- GitLab has no batch "Submit Review" API like GitHub. Post DiffNotes individually.
- To find a discussion or note ID: `glab api "projects/:id/merge_requests/:iid/discussions" --paginate`

### Managing Issues

```bash
# Create issue with labels
glab issue create --title "Bug in login" --label=bug

# Link MR to issue
glab mr create --title "Fix login" --description "Closes #<issue-number>"

# List your assigned issues
glab issue list --assignee=@me
```

### Monitoring CI/CD

```bash
# Watch pipeline in progress
glab pipeline ci view

# Check pipeline status
glab ci status

# View logs if failed
glab ci trace

# Retry failed pipeline
glab ci retry

# Lint CI config before pushing
glab ci lint
```

## Common Patterns

### Working Outside Repository Context

When not in a Git repository, specify the repository:
```bash
glab mr list -R owner/repo
glab issue list -R owner/repo
```

### Self-Hosted GitLab

Set hostname for all commands:
```bash
export GITLAB_HOST=gitlab.example.org
# or per-command
glab repo clone gitlab.example.org/owner/repo
```

### Listing Unresolved MR Comments

```bash
glab api "projects/:id/merge_requests/{mr}/discussions?per_page=100" | jq '[.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | {id: .notes[0].id, body: .notes[0].body[0:100], path: .notes[0].position.new_path, line: .notes[0].position.new_line}]'
```

### Automation and Scripting

Use JSON output for parsing:
```bash
glab mr list --output=json | jq '.[] | .title'
```

### Replying to MR Notes/Threads

`glab mr note` creates standalone comments. To reply within a discussion thread, use the API:

```bash
# 1. Find the discussion_id containing the note
glab api "projects/:id/merge_requests/{mr}/discussions" | jq '.[] | select(.notes[].id == {note_id}) | .id'

# 2. Post reply to the discussion thread
glab api --method POST "projects/:id/merge_requests/{mr}/discussions/{discussion_id}/notes" --field body="Your reply"
```

Example:
```bash
# Get discussion_id for note 13698970
glab api "projects/:id/merge_requests/1013/discussions" | jq '.[] | select(.notes[].id == 13698970) | {id}'
# Returns: {"id": "5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c"}

# Reply to that thread
glab api --method POST "projects/:id/merge_requests/1013/discussions/5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c/notes" --field body="Thanks for the review!"
```

### Using the API Command

The `glab api` command provides direct GitLab API access:

```bash
# Basic API call
glab api projects/:id/merge_requests

# IMPORTANT: Pagination uses query parameters in URL, NOT flags
# ❌ WRONG: glab api --per-page=100 projects/:id/jobs
# ✓ CORRECT: glab api "projects/:id/jobs?per_page=100"

# Auto-fetch all pages
glab api --paginate "projects/:id/pipelines/123/jobs?per_page=100"

# POST with data
glab api --method POST projects/:id/issues --field title="Bug" --field description="Details"
```

## Best Practices