glab

---
name: glab
description: Expert guidance for using the GitLab CLI (glab) to manage GitLab issues, merge requests, CI/CD pipelines, repositories, and other GitLab operations from the command line. Use this skill when the user needs to interact with GitLab resources or perform GitLab workflows.
---

# 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

1. **Verify authentication** before executing commands: `glab auth status`
2. **Use `--help`** to explore command options: `glab <command> --help`
3. **Link MRs to issues** using "Closes #123" in MR description
4. **Lint CI config** before pushing: `glab ci lint`
5. **Check repository context** when commands fail: `git remote -v`

## Common Commands Quick Reference

**Merge Requests:**
- `glab mr list --assignee=@me` - Your assigned MRs
- `glab mr list --reviewer=@me` - MRs for you to review
- `glab mr create` - Create new MR
- `glab mr checkout <number>` - Test MR locally
- `glab mr approve <number>` - Approve MR
- `glab mr merge <number>` - Merge approved MR

**Issues:**
- `glab issue list` - List all issues
- `glab issue create` - Create new issue
- `glab issue close <number>` - Close issue

**CI/CD:**
- `glab pipeline ci view` - Watch pipeline
- `glab ci status` - Check status
- `glab ci lint` - Validate .gitlab-ci.yml
- `glab ci retry` - Retry failed pipeline

**Repository:**
- `glab repo clone owner/repo` - Clone repository
- `glab repo view` - View repo details
- `glab repo fork` - Fork repository

## Progressive Disclosure

For detailed command documentation, refer to:
- **references/commands-detailed.md** - Comprehensive command reference with all flags and options
- **references/quick-reference.md** - Condensed command cheat sheet
- **references/troubleshooting.md** - Detailed error scenarios and solutions

Load these references when:
- User needs specific flag or option details
- Troubleshooting authentication or connection issues
- Working with advanced features (API, schedules, variables, etc.)

## Common Issues Quick Fixes

**"command not found: glab"** - Install glab or verify PATH

**"401 Unauthorized"** - Run `glab auth login`

**"404 Project Not Found"** - Verify repository name and access permissions

**"not a git repository"** - Navigate to repo or use `-R owner/repo` flag

**"source branch already has a merge request"** - Use `glab mr list` to find existing MR

For detailed troubleshooting, load **references/troubleshooting.md**.

## Notes

- glab auto-detects repository context from Git remote
- Most commands have `--web` flag to open in browser
- Use `--output=json` for scripting and automation
- Multiple GitLab accounts can be authenticated simultaneously
- Commands respect Git configuration and current repository context

• SKILL.md 8 KB
• references/commands-detailed.md 12 KB
• references/quick-reference.md 4 KB
• references/troubleshooting.md 11 KB