glab

What this skill does

# glab - GitLab CLI

Command-line interface for GitLab. Binary name: `glab`.

## Repository Context

glab auto-detects the GitLab project from the git remote in the current directory. Override with `--repo` (`-R`):

```bash
glab mr list                              # auto-detected from git remote
glab mr list -R group/project             # explicit project
glab mr list -R group/namespace/project
```

## Identifying MRs

MR commands accept an MR IID number, a branch name, or nothing (current branch):

```bash
glab mr view 123           # by MR IID
glab mr view feature-x     # by branch name
glab mr view               # current branch's MR
```

---

## Files for tool arguments

For any `glab` argument longer than a few words (MR descriptions, comments, job logs), put the content in a file and pass it via `"$(cat <path>)"` instead of inlining. Edits stay cheap, and the Write tool diff shows the user exactly what changed between revisions.

- If the content already exists as a file on disk, use it directly — do **not** copy it to `/tmp` first.
- When generating new content, write it to `/tmp/<unique-slug>.md` including the MR number, branch name, or job name (e.g., `/tmp/mr-desc-123.md`, `/tmp/glab-job-build-123.log`). **Never** use generic names like `/tmp/mr-description.md` — they collide across MRs.
- Reuse the same file for the same MR/entity across edits.

---

## Creating a Merge Request

```bash
glab mr create --fill --fill-commit-body --yes -b main --draft -a user1 --reviewer user2 -l bug
```

| Flag | Short | Description |
|------|-------|-------------|
| `--title` | `-t` | MR title |
| `--description` | `-d` | Description (`"-"` opens editor) |
| `--fill` | `-f` | Use commit info, auto-push branch |
| `--fill-commit-body` | | Include all commit bodies (with `--fill`) |
| `--draft` | | Create as draft |
| `--assignee` | `-a` | Assign by username (comma-separated or repeated) |
| `--reviewer` | | Request review by username |
| `--label` | `-l` | Add labels |
| `--milestone` | `-m` | Assign milestone |
| `--target-branch` | `-b` | Target branch |
| `--source-branch` | `-s` | Source branch (default: current) |
| `--push` | | Push branch before creating |
| `--remove-source-branch` | | Remove source branch on merge |
| `--squash-before-merge` | | Squash commits on merge |
| `--related-issue` | `-i` | Link to issue IID |
| `--copy-issue-labels` | | Copy labels from linked issue |
| `--yes` | `-y` | Skip confirmation prompt |
| `--web` | `-w` | Continue in browser |

---

## Viewing Current MR

```bash
glab mr view --comments -F json
```

| Flag | Short | Description |
|------|-------|-------------|
| `--comments` | `-c` | Include comments and activities |
| `--system-logs` | `-s` | Include system activities |
| `--output` | `-F` | Format: `text`, `json` |
| `--web` | `-w` | Open in browser |
| `--page` | `-p` | Page number for comments |
| `--per-page` | `-P` | Items per page (default 20) |

---

## Updating MR Title and Description

```bash
glab mr update 123 --title "New title" --description "New description" --ready -l bug --reviewer +user2
```

Assignee/reviewer prefix modifiers: `+` to add, `!` or `-` to remove. No prefix replaces all.

| Flag | Short | Description |
|------|-------|-------------|
| `--title` | `-t` | MR title |
| `--description` | `-d` | Description (`"-"` opens editor) |
| `--draft` | | Mark as draft |
| `--ready` | `-r` | Mark as ready |
| `--label` | `-l` | Add labels |
| `--unlabel` | `-u` | Remove labels |
| `--assignee` | `-a` | Set assignees (`+` add, `!` remove, bare replaces all) |
| `--unassign` | | Remove all assignees |
| `--reviewer` | | Set reviewers (`+` add, `!` remove, bare replaces all) |
| `--milestone` | `-m` | Set milestone (`""` or `0` to unset) |
| `--target-branch` | | Change target branch |
| `--remove-source-branch` | | Toggle remove source branch on merge |
| `--squash-before-merge` | | Toggle squash on merge |
| `--lock-discussion` | | Lock discussion |
| `--unlock-discussion` | | Unlock discussion |
| `--yes` | `-y` | Skip confirmation |

---

## MR Discussions and Notes

`glab mr note` can add comments, but listing discussions and replying to threads requires the API.

### Add a Comment

```bash
glab mr note 123 -m "Looks good!"
```

| Flag | Short | Description |
|------|-------|-------------|
| `--message` | `-m` | Comment text |
| `--unique` | | Skip if identical comment already exists |

### List MR Discussions (API)

Discussions are threaded conversations. Each discussion has an `id` and contains `notes`.

```bash
glab api projects/:id/merge_requests/123/discussions --paginate
```

### Reply to a Discussion Thread (API)

```bash
glab api -X POST projects/:id/merge_requests/123/discussions/<discussion_id>/notes \
  -f body="Reply text"
```

### Create a New Discussion Thread (API)

```bash
glab api -X POST projects/:id/merge_requests/123/discussions \
  -f body="Starting a new thread"
```

### Resolve / Unresolve a Discussion (API)

```bash
glab api -X PUT projects/:id/merge_requests/123/discussions/<discussion_id> \
  -F resolved=true
```

---

## MR Pipeline and Job Logs

### View Pipeline Status

```bash
glab ci status --compact
glab ci get --with-job-details -F json
```

| Command | Description |
|---------|-------------|
| `glab ci status` | Current branch pipeline status |
| `glab ci status --live` | Real-time updates until done |
| `glab ci status --compact` | Compact view |
| `glab ci get` | Pipeline details with job list |
| `glab ci get --with-job-details` | Extended job info |
| `glab ci get -F json` | JSON output |

### View Job Logs

**Always redirect job logs to a temp file** — the output can be thousands of lines and will waste context tokens.

```bash
glab ci trace <job-name> > /tmp/glab-job-<job-name>-$(date +%s).log 2>&1
```

**DO NOT** run `glab ci trace` without redirecting to a file.

| Flag | Short | Description |
|------|-------|-------------|
| `--branch` | `-b` | Branch to search for the job |
| `--pipeline-id` | `-p` | Pipeline ID to search for the job |

### Retry / Trigger Jobs

```bash
glab ci retry <job-name>           # retry a failed job
glab ci trigger <job-name>         # trigger a manual job
```

---

## API (Raw HTTP Requests)

Direct GitLab API access for anything not covered by dedicated commands.

```bash
glab api projects/:id/members                                    # GET (default)
glab api projects/:id/labels -f name=bug -f color=#FF0000        # POST (default when params present)
glab api -X PUT projects/:id -f name="new-name"                  # explicit method
```

### Pagination

`--paginate` fetches **all pages** sequentially. Without it, you only get the first page.

```bash
glab api projects/:id/issues --paginate --output ndjson | jq 'select(.state == "opened")'
```

Output formats:
- `json` (default) — pretty-printed, arrays merged into a single JSON array
- `ndjson` — one JSON object per line, memory-efficient, works with `jq`

### Endpoint Placeholders

Auto-resolved from the git remote: `:id`, `:fullpath`, `:group`, `:namespace`, `:repo`, `:branch`, `:user`, `:username`

### Parameter Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--raw-field` | `-f` | String parameter |
| `--field` | `-F` | Typed parameter (`true`/`false`/integers auto-converted, `@file` reads from file) |
| `--method` | `-X` | HTTP method (default: GET without params, POST with) |
| `--paginate` | | Fetch all pages |
| `--output` | | Format: `json` (default), `ndjson` |
| `--header` | `-H` | Additional HTTP header |
| `--hostname` | | Override GitLab host |
| `--include` | `-i` | Include response headers |
| `--input` | | Request body from file (`-` for stdin) |
| `--silent` | | Don't print response body |

---

## Other Commands

Discover flags with `--help`:

| Group | Description |
|-------|-------------|
| `mr list`, `mr diff`, `mr merge`, `mr approve`, `mr rebase`, `mr checkout` | MR management |
| `issue list`, `issue view`, `issue create`,