GitLabgitlab-org

cli

main
ply10 git calls283 ms103 KiB7 cachedprotocol v2
350 lines15 KiBRaw

GitLab CLI (glab)

glab is pre-configured and available in your environment. Use it for all GitLab operations. Run glab <command> --help for detailed flag information.

Quick reference

shell
# Issues
glab issue view <iid>
glab issue list --label "bug,priority::1"
glab issue create --title "title" --description-file /tmp/desc.md
glab issue note <iid> -m "comment text"

# Merge requests
glab mr create --push --title "fix: title" --description-file /tmp/desc.md
glab mr view <iid>
glab mr list --assignee <user>
glab mr update <iid> --description-file /tmp/desc.md
glab mr note create <iid> -m "comment text"

# CI/CD
glab ci status
glab ci status --output json
glab ci list
glab ci get --merge-request <iid> --with-job-details
glab ci get --pipeline-id <id> --output json
glab ci retry <job-id>
glab api projects/:id/jobs/<job-id>/trace

# Machine-readable output
glab mr list --output json | jq '.[].title'

Templates: Check .gitlab/merge_request_templates/ and .gitlab/issue_templates/ for project-specific templates.

References: Always use full URLs in note/comment bodies (e.g. https://gitlab.com/org/project/-/issues/123) instead of short references (#123, !456). This applies to issues, merge requests, epics, and so on. Short refs resolve against project context and render as literal text on group-level items (epics, group work items); full URLs expand everywhere.

Comments and discussions

Use the mr note subcommands (create, resolve, reopen); flags on the root glab mr note command are deprecated.

Short, inline bodies — pass -m

shell
glab issue note        <iid> -m "comment text"
glab mr note create    <iid> -m "comment text"
glab incident note     <iid> -m "comment text"

# Cross-project
glab mr note create <iid> -m "..." --repo group/project

Long or Markdown bodies — pipe to stdin

glab mr note create, glab mr note update, glab mr note draft create, glab mr note draft update, glab issue note, and glab incident note read the body from stdin when -m is omitted and the input is a pipe. This avoids shell-quoting pitfalls (backticks, $, backslashes, apostrophes) and is the safest pattern for non-interactive use. A piped body also works with --attach <file>: the attachment links are added after the body.

shell
# From a file
glab mr note create <iid> < /tmp/body.md

# Inline literal multi-line body — quoted heredoc, no shell expansion inside
glab mr note create <iid> << 'EOF'
Your **markdown** comment.
Code blocks and `inline code`, $variables, and \backslashes are all literal.
EOF

glab issue note <iid> << 'EOF'
It's the same for issues and incidents.
EOF

# Body from a file, with a screenshot attached after it
glab mr note create <iid> --attach ./screenshot.png < /tmp/body.md

For descriptions on glab issue create / glab issue update / glab mr create / glab mr update / glab work-items create / glab work-items update, pass --description-file. A path of - reads from stdin, so a quoted heredoc works directly:

shell
glab mr create --push --title "fix: title" --description-file - << 'EOF'
## What does this MR do?

It's a fix for `foo`.
EOF

glab mr update <iid> --description-file /tmp/desc.md

Do not nest a heredoc inside command substitution, such as --description "$(cat << 'EOF' ... EOF)" or -m "$(cat << 'EOF' ... EOF)". The default /bin/bash on macOS is bash 3.2, which fails with unexpected EOF while looking for matching '' when the body contains an apostrophe. Feed the heredoc to --description-file - or to stdin instead.

Threaded replies on merge requests

glab mr note create supports --reply <discussion-id> for replying inside an MR thread. The value can be the full discussion ID or a unique prefix of at least 8 characters.

Diff comments accept a single line (--line 42), a range (--line 10:15), a removed line (--old-line 7), or no line for a file-level comment.

shell
glab mr note create  <iid> --reply <discussion-id> -m "I agree!"
glab mr note create  <iid> --file main.go --line 42 -m "Needs refactoring"
glab mr note create  <iid> --file main.go --line 10:15 -m "Extract this block"
glab mr note create  <iid> --file main.go --old-line 7 -m "Why was this removed?"
glab mr note create  <iid> --file main.go -m "General comment on this file"
glab mr note create  <iid> -m "LGTM" --unique    # idempotent: skip if same body exists

glab mr note resolve / reopen take the MR identifier followed by the discussion identifier. The identifier can be a discussion ID (full 40-char hex or 8+ char prefix) or a note ID (integer; the parent discussion is looked up automatically):

shell
glab mr note resolve <iid> <discussion-id>
glab mr note resolve <iid> <note-id>           # integer note ID also works
glab mr note reopen  <iid> <discussion-id>

Threaded replies on issues, incidents, and work items

The CLI does not wrap threaded replies for these, so you fall back to glab api. For any non-trivial body, write it to a file and post the file rather than inlining rich Markdown — inlined backticks, $, newlines, and a leading @ all break (see Content-type guidance):

shell
# Discover the discussion ID
glab api projects/:id/issues/<iid>/discussions \
  | jq '.[] | {id, body: .notes[0].body}'

# Build the body in a file, then post it with -F body=@file
cat > /tmp/reply.md << 'EOF'
@user — here's the result, with `code`, a $variable, and an emoji ✅.
EOF
glab api projects/:id/issues/<iid>/discussions/<discussion-id>/notes \
  -F body=@/tmp/reply.md

For a short, plain reply you can still inline it with -f body="reply text".

API calls

glab api auto-prepends /api/v4/. Use relative paths:

shell
glab api user                              # NOT /api/v4/user
glab api projects/:id/merge_requests
glab api projects/:id/issues | jq '.[0]'

Placeholders

glab api expands these built-in tokens in a path, a field value, or inline JSON:

:branch :fullpath :group :id :namespace :repo :user :username

:user and :username work anywhere. The rest are read from the current repository, so they need a Git checkout with a GitLab remote. Outside one, or to target a different project, supply the value instead:

shell
glab api projects/:id/issues                    # inside a checkout
glab api projects/:id/issues -R group/project   # any project; placeholder still expands
glab api projects/group%2Fproject/issues        # literal path -- %2F is required
glab api projects/1234/issues                   # numeric project ID

To insert any other value, define your own placeholder with --placeholder <name>=<value>. In the path, glab encodes the value as a single segment, so you don't need to write %2F by hand. In -F values it is sent unchanged. For a query string value, pass it as a field with -X GET -F rather than in the path:

shell
glab api projects/:fullpath/repository/branches/:target --placeholder target=feature/login
glab api projects/:id/issues -X GET -F search=:term --placeholder term='a&b'

Anything else beginning with a colon is not a placeholder. glab sends it to the API verbatim, so the request fails at the server rather than in glab.

Content-type guidance

When using -f for PUT/POST, pass simple key=value pairs. Array bracket syntax like ids[]=1 is not supported:

shell
# -f / --raw-field — literal string value
glab api projects/:id/merge_requests/42 -X PUT -f "assignee_id=1"
glab api projects/:id/issues/42/notes -f body="comment text"

# -F / --field — reads @file as a string. The leading @ means "read this
# file", so only pass a real path here. A literal body that starts with @
# (e.g. "@user thanks") must NOT go through -F — it would be read as a
# filename. Use -f for literal inline text, or write the body to a file and
# point -F at the file (recommended for rich/markdown bodies).
glab api projects/:id/issues/42/notes -F body=@/tmp/comment.md

# --input — raw request body from a file (or '-' for stdin). Does NOT set
# Content-Type. Without the header, JSON endpoints return HTTP 415.
glab api projects/:id/issues/42/notes \
  --input /tmp/body.json \
  -H "Content-Type: application/json"

# --form — multipart/form-data. Required for endpoints that take a real file
# upload, such as project or group uploads and wiki attachments. -F does not
# do this: it reads the file into a text field, and the endpoint rejects the
# request with HTTP 400.
#
# IMPORTANT: --form is mutually exclusive with -f, -F, and --input. Every
# field in a multipart request must use --form
glab api projects/:id/uploads --method POST --form "file=@screenshot.png"

# Wiki attachment — both fields must use --form
glab api projects/:fullpath/wikis/attachments --method POST \
  --form "file=@screenshot.png" --form "branch=main"

Arrays and nested objects

-F / --field parses a value that starts with [ or { as JSON, so arrays and nested objects go inline without a file. Placeholders are expanded inside the JSON. Invalid JSON returns an error rather than being sent as a string.

shell
# Array of strings
glab api -X PUT projects/:id -F 'topics=["my-topic","GitLab"]'

# Nested object, with a placeholder expanded inside it
glab api projects/:id/merge_requests/42/discussions -X POST \
  -F body="looks good" \
  -F 'position={"position_type":"text","new_path":"main.go","new_line":42}'

# Empty array clears a field
glab api -X PUT projects/:id -F 'topics=[]'

-f / --raw-field never parses JSON: a bracketed value like -f 'scopes=[api,read_api]' is sent as the literal string. Use -F with real JSON for arrays. On GET and DELETE requests, and whenever --input is used, -F arrays are serialized as repeated key[]= query parameters.

Common mistakes

  • -m or piped stdin is required on note commands — with neither, glab mr note create, glab issue note, and glab incident note open $EDITOR on a TTY, which hangs in non-interactive environments.
  • Use glab mr note create, not glab mr note -m — the --message, --unique, --resolve, and --unresolve flags on the root glab mr note command are deprecated. Use the create, resolve, and reopen subcommands instead.
  • Editor-opening flags are unsafe in agent environments — avoid --description "-" on issue create / mr create / mr update and avoid omitting -m on note commands. Pass an explicit value or pipe from stdin instead.
  • glab issue note and glab incident note only post root-level comments — use glab mr note create --reply for MRs, or glab api .../discussions/<id>/notes for issues/incidents (write the body to a file and pass -F body=@file for anything non-trivial).
  • A note with only an attachment needs </dev/null in scripts — when stdin is not a terminal, note commands read it as the body and wait until it closes. Run glab mr note create <iid> --attach ./shot.png </dev/null so glab neither waits on an open pipe nor consumes a loop's input.
  • --attach - uses stdin for the file — the body must then come from -m, for example pngpaste - | glab mr note create <iid> -m "Repro" --attach -.
  • -F does not upload files — -F file=@x.png sends the file contents as a string field, and upload endpoints reject it with HTTP 400. Use --form file=@x.png for multipart uploads. -F reads a file only to fill a text field, such as a note body. Also, --form is mutually exclusive with -f, -F, and --input — every field in a multipart request must use --form (e.g. --form "file=@x.png" --form "branch=main").
  • --input requires an explicit Content-Type header — glab api --input file.json sends raw bytes without setting Content-Type, causing HTTP 415. Add -H "Content-Type: application/json" or use -f / -F instead.
  • glab ci retry takes a job ID, not a pipeline ID — to retry an entire pipeline, use glab api projects/:id/pipelines/<id>/retry -X POST.
  • glab ci trace streams — it blocks until the job finishes. For agents, use glab ci get for pipeline state or glab api projects/:id/jobs/<job-id>/trace to fetch a finished log.
  • glab ci view is interactive — terminal UI that blocks. Use glab ci status or glab ci get for pipeline state instead.
  • Always --push on glab mr create — without it the remote branch may not exist and MR creation fails.
  • No --state on mr list — use --all, --merged, or --closed.
  • No --body flag — --body is a gh flag. glab uses --description.
  • Labels — --label to add, --unlabel to remove. Scoped labels like status::doing auto-replace within their scope.

Contributing improvements

This skill ships inside glab. Its front matter records where it is maintained: metadata.source-project and metadata.source-path.

If any guidance here is inaccurate or outdated, such as a command that no longer works, a wrong flag, or incorrect API behavior:

  1. Use glab api to read the file <source-path>/SKILL.md in source-project on main. If the issue is already fixed there, use that guidance instead of opening another merge request.
  2. After a release with the fix, upgrade glab. Refresh your copy:
    • glab skills get glab: the upgraded binary already has it.
    • Installed with glab skills install (project or user): a copy is glab-installed only if its front matter has source-project set to gitlab-org/cli. If every glab/ in both locations is glab-installed, run glab skills update glab from the project. It replaces all of them. Otherwise, refresh only the glab-installed ones with glab skills install glab --force from that project (add --global for the user location). Ask the user about any copy without source-project.
    • Installed with --path: run glab skills install glab --path <parent-dir> --force.
    • Third-party copy: refresh it at its source.
  3. If the problem is still present on main, confirm with the user, then open a merge request against source-project with the fix. Keep changes focused: one fix per merge request, with a Conventional Commits message.
1---
2name: glab
3description: >
4 GitLab CLI (glab) for working with GitLab from the command line. Read this
5 skill before running any `glab` or GitLab API command — it applies to every
6 GitLab operation, whether reading or writing (for example merge requests,
7 issues, work items, discussions and threaded replies, comments, CI/CD
8 pipelines, releases, packages, members, and project settings). Whenever a
9 task touches GitLab in any way, consult this skill first so you use the
10 correct, safe command on the first try. Prefer glab over raw API calls for
11 all GitLab operations.
12metadata:
13 source-project: gitlab-org/cli
14 source-path: internal/commands/skills/bundled/assets/glab
15---
17# GitLab CLI (glab)
19`glab` is pre-configured and available in your environment. Use it for all
20GitLab operations. Run `glab <command> --help` for detailed flag information.
22## Quick reference
24```shell
25# Issues
26glab issue view <iid>
27glab issue list --label "bug,priority::1"
28glab issue create --title "title" --description-file /tmp/desc.md
29glab issue note <iid> -m "comment text"
31# Merge requests
32glab mr create --push --title "fix: title" --description-file /tmp/desc.md
33glab mr view <iid>
34glab mr list --assignee <user>
35glab mr update <iid> --description-file /tmp/desc.md
36glab mr note create <iid> -m "comment text"
38# CI/CD
39glab ci status
40glab ci status --output json
41glab ci list
42glab ci get --merge-request <iid> --with-job-details
43glab ci get --pipeline-id <id> --output json
44glab ci retry <job-id>
45glab api projects/:id/jobs/<job-id>/trace
47# Machine-readable output
48glab mr list --output json | jq '.[].title'
49```
51**Templates:** Check `.gitlab/merge_request_templates/` and
52`.gitlab/issue_templates/` for project-specific templates.
54**References:** Always use full URLs in note/comment bodies (e.g.
55`https://gitlab.com/org/project/-/issues/123`) instead of short references
56(`#123`, `!456`). This applies to issues, merge requests, epics, and so on.
57Short refs resolve against project context and render as literal text on
58group-level items (epics, group work items); full URLs expand everywhere.
60## Comments and discussions
62Use the `mr note` subcommands (`create`, `resolve`, `reopen`); flags on the
63root `glab mr note` command are deprecated.
65### Short, inline bodies — pass `-m`
67```shell
68glab issue note <iid> -m "comment text"
69glab mr note create <iid> -m "comment text"
70glab incident note <iid> -m "comment text"
72# Cross-project
73glab mr note create <iid> -m "..." --repo group/project
74```
76### Long or Markdown bodies — pipe to stdin
78`glab mr note create`, `glab mr note update`, `glab mr note draft create`,
79`glab mr note draft update`, `glab issue note`, and `glab incident note` read
80the body from stdin when `-m` is omitted and the input is a pipe. This avoids
81shell-quoting pitfalls (backticks, `$`, backslashes, apostrophes) and is the
82safest pattern for non-interactive use. A piped body also works with
83`--attach <file>`: the attachment links are added after the body.
85```shell
86# From a file
87glab mr note create <iid> < /tmp/body.md
89# Inline literal multi-line body — quoted heredoc, no shell expansion inside
90glab mr note create <iid> << 'EOF'
91Your **markdown** comment.
92Code blocks and `inline code`, $variables, and \backslashes are all literal.
93EOF
95glab issue note <iid> << 'EOF'
96It's the same for issues and incidents.
97EOF
99# Body from a file, with a screenshot attached after it
100glab mr note create <iid> --attach ./screenshot.png < /tmp/body.md
101```
103For descriptions on `glab issue create` / `glab issue update` /
104`glab mr create` / `glab mr update` / `glab work-items create` /
105`glab work-items update`, pass `--description-file`. A path of `-` reads
106from stdin, so a quoted heredoc works directly:
108```shell
109glab mr create --push --title "fix: title" --description-file - << 'EOF'
110## What does this MR do?
112It's a fix for `foo`.
113EOF
115glab mr update <iid> --description-file /tmp/desc.md
116```
118Do not nest a heredoc inside command substitution, such as
119`--description "$(cat << 'EOF' ... EOF)"` or `-m "$(cat << 'EOF' ... EOF)"`.
120The default `/bin/bash` on macOS is bash 3.2, which fails with
121`unexpected EOF while looking for matching ''` when the body contains an
122apostrophe. Feed the heredoc to `--description-file -` or to stdin instead.
124### Threaded replies on merge requests
126`glab mr note create` supports `--reply <discussion-id>` for replying inside
127an MR thread. The value can be the full discussion ID or a unique prefix of
128at least 8 characters.
130Diff comments accept a single line (`--line 42`), a range (`--line 10:15`),
131a removed line (`--old-line 7`), or no line for a file-level comment.
133```shell
134glab mr note create <iid> --reply <discussion-id> -m "I agree!"
135glab mr note create <iid> --file main.go --line 42 -m "Needs refactoring"
136glab mr note create <iid> --file main.go --line 10:15 -m "Extract this block"
137glab mr note create <iid> --file main.go --old-line 7 -m "Why was this removed?"
138glab mr note create <iid> --file main.go -m "General comment on this file"
139glab mr note create <iid> -m "LGTM" --unique # idempotent: skip if same body exists
140```
142`glab mr note resolve` / `reopen` take the MR identifier followed by the
143discussion identifier. The identifier can be a discussion ID (full 40-char
144hex or 8+ char prefix) or a note ID (integer; the parent discussion is
145looked up automatically):
147```shell
148glab mr note resolve <iid> <discussion-id>
149glab mr note resolve <iid> <note-id> # integer note ID also works
150glab mr note reopen <iid> <discussion-id>
151```
153### Threaded replies on issues, incidents, and work items
155The CLI does not wrap threaded replies for these, so you fall back to
156`glab api`. **For any non-trivial body, write it to a file and post the file**
157rather than inlining rich Markdown — inlined backticks, `$`, newlines, and a
158leading `@` all break (see [Content-type guidance](#content-type-guidance)):
160```shell
161# Discover the discussion ID
162glab api projects/:id/issues/<iid>/discussions \
163 | jq '.[] | {id, body: .notes[0].body}'
165# Build the body in a file, then post it with -F body=@file
166cat > /tmp/reply.md << 'EOF'
167@user — here's the result, with `code`, a $variable, and an emoji ✅.
168EOF
169glab api projects/:id/issues/<iid>/discussions/<discussion-id>/notes \
170 -F body=@/tmp/reply.md
171```
173For a short, plain reply you can still inline it with `-f body="reply text"`.
175## API calls
177`glab api` auto-prepends `/api/v4/`. Use relative paths:
179```shell
180glab api user # NOT /api/v4/user
181glab api projects/:id/merge_requests
182glab api projects/:id/issues | jq '.[0]'
183```
185### Placeholders
187`glab api` expands these built-in tokens in a path, a field value, or inline JSON:
189`:branch` `:fullpath` `:group` `:id` `:namespace` `:repo` `:user` `:username`
191`:user` and `:username` work anywhere. The rest are read from the current
192repository, so they need a Git checkout with a GitLab remote. Outside one, or to
193target a different project, supply the value instead:
195```shell
196glab api projects/:id/issues # inside a checkout
197glab api projects/:id/issues -R group/project # any project; placeholder still expands
198glab api projects/group%2Fproject/issues # literal path -- %2F is required
199glab api projects/1234/issues # numeric project ID
200```
202To insert any other value, define your own placeholder with
203`--placeholder <name>=<value>`. In the path, glab encodes the value as a single
204segment, so you don't need to write `%2F` by hand. In `-F` values it is sent
205unchanged. For a query string value, pass it as a field with `-X GET -F` rather
206than in the path:
208```shell
209glab api projects/:fullpath/repository/branches/:target --placeholder target=feature/login
210glab api projects/:id/issues -X GET -F search=:term --placeholder term='a&b'
211```
213Anything else beginning with a colon is **not** a placeholder. glab sends it to
214the API verbatim, so the request fails at the server rather than in glab.
216### Content-type guidance
218When using `-f` for PUT/POST, pass simple `key=value` pairs. Array bracket
219syntax like `ids[]=1` is not supported:
221```shell
222# -f / --raw-field — literal string value
223glab api projects/:id/merge_requests/42 -X PUT -f "assignee_id=1"
224glab api projects/:id/issues/42/notes -f body="comment text"
226# -F / --field — reads @file as a string. The leading @ means "read this
227# file", so only pass a real path here. A literal body that starts with @
228# (e.g. "@user thanks") must NOT go through -F — it would be read as a
229# filename. Use -f for literal inline text, or write the body to a file and
230# point -F at the file (recommended for rich/markdown bodies).
231glab api projects/:id/issues/42/notes -F body=@/tmp/comment.md
233# --input — raw request body from a file (or '-' for stdin). Does NOT set
234# Content-Type. Without the header, JSON endpoints return HTTP 415.
235glab api projects/:id/issues/42/notes \
236 --input /tmp/body.json \
237 -H "Content-Type: application/json"
239# --form — multipart/form-data. Required for endpoints that take a real file
240# upload, such as project or group uploads and wiki attachments. -F does not
241# do this: it reads the file into a text field, and the endpoint rejects the
242# request with HTTP 400.
244# IMPORTANT: --form is mutually exclusive with -f, -F, and --input. Every
245# field in a multipart request must use --form
246glab api projects/:id/uploads --method POST --form "file=@screenshot.png"
248# Wiki attachment — both fields must use --form
249glab api projects/:fullpath/wikis/attachments --method POST \
250 --form "file=@screenshot.png" --form "branch=main"
251```
253### Arrays and nested objects
255`-F` / `--field` parses a value that starts with `[` or `{` as JSON, so arrays
256and nested objects go inline without a file. Placeholders are expanded inside
257the JSON. Invalid JSON returns an error rather than being sent as a string.
259```shell
260# Array of strings
261glab api -X PUT projects/:id -F 'topics=["my-topic","GitLab"]'
263# Nested object, with a placeholder expanded inside it
264glab api projects/:id/merge_requests/42/discussions -X POST \
265 -F body="looks good" \
266 -F 'position={"position_type":"text","new_path":"main.go","new_line":42}'
268# Empty array clears a field
269glab api -X PUT projects/:id -F 'topics=[]'
270```
272`-f` / `--raw-field` never parses JSON: a bracketed value like
273`-f 'scopes=[api,read_api]'` is sent as the literal string. Use `-F` with real
274JSON for arrays. On GET and DELETE requests, and whenever `--input` is used,
275`-F` arrays are serialized as repeated `key[]=` query parameters.
277## Common mistakes
279- **`-m` or piped stdin is required on `note` commands** — with neither,
280 `glab mr note create`, `glab issue note`, and `glab incident note` open
281 `$EDITOR` on a TTY, which hangs in non-interactive environments.
282- **Use `glab mr note create`, not `glab mr note -m`** — the `--message`,
283 `--unique`, `--resolve`, and `--unresolve` flags on the root `glab mr note`
284 command are deprecated. Use the `create`, `resolve`, and `reopen`
285 subcommands instead.
286- **Editor-opening flags are unsafe in agent environments** — avoid
287 `--description "-"` on `issue create` / `mr create` / `mr update` and
288 avoid omitting `-m` on `note` commands. Pass an explicit value or pipe
289 from stdin instead.
290- **`glab issue note` and `glab incident note` only post root-level
291 comments** — use `glab mr note create --reply` for MRs, or
292 `glab api .../discussions/<id>/notes` for issues/incidents (write the body
293 to a file and pass `-F body=@file` for anything non-trivial).
294- **A note with only an attachment needs `</dev/null` in scripts** — when
295 stdin is not a terminal, `note` commands read it as the body and wait until
296 it closes. Run `glab mr note create <iid> --attach ./shot.png </dev/null`
297 so glab neither waits on an open pipe nor consumes a loop's input.
298- **`--attach -` uses stdin for the file** — the body must then come from
299 `-m`, for example `pngpaste - | glab mr note create <iid> -m "Repro" --attach -`.
300- **`-F` does not upload files** — `-F file=@x.png` sends the file contents as
301 a string field, and upload endpoints reject it with HTTP 400. Use `--form
302 file=@x.png` for multipart uploads. `-F` reads a file only to fill a *text*
303 field, such as a note body. Also, `--form` is mutually exclusive with `-f`,
304 `-F`, and `--input` — every field in a multipart request must use `--form`
305 (e.g. `--form "file=@x.png" --form "branch=main"`).
306- **`--input` requires an explicit `Content-Type` header** — `glab api
307 --input file.json` sends raw bytes without setting Content-Type, causing
308 HTTP 415. Add `-H "Content-Type: application/json"` or use `-f` / `-F`
309 instead.
310- **`glab ci retry` takes a job ID, not a pipeline ID** — to retry an
311 entire pipeline, use `glab api projects/:id/pipelines/<id>/retry -X POST`.
312- **`glab ci trace` streams** — it blocks until the job finishes. For
313 agents, use `glab ci get` for pipeline state or
314 `glab api projects/:id/jobs/<job-id>/trace` to fetch a finished log.
315- **`glab ci view` is interactive** — terminal UI that blocks. Use
316 `glab ci status` or `glab ci get` for pipeline state instead.
317- **Always `--push` on `glab mr create`** — without it the remote branch
318 may not exist and MR creation fails.
319- **No `--state` on `mr list`** — use `--all`, `--merged`, or `--closed`.
320- **No `--body` flag** — `--body` is a `gh` flag. `glab` uses `--description`.
321- **Labels** — `--label` to add, `--unlabel` to remove. Scoped labels like
322 `status::doing` auto-replace within their scope.
324## Contributing improvements
326This skill ships inside `glab`. Its front matter records where it is
327maintained: `metadata.source-project` and `metadata.source-path`.
329If any guidance here is inaccurate or outdated, such as a command that no
330longer works, a wrong flag, or incorrect API behavior:
3321. Use `glab api` to read the file `<source-path>/SKILL.md` in
333 `source-project` on `main`. If the issue is already fixed there, use that
334 guidance instead of opening another merge request.
3352. After a release with the fix, upgrade `glab`. Refresh your copy:
336 - `glab skills get glab`: the upgraded binary already has it.
337 - Installed with `glab skills install` (project or user): a copy is
338 glab-installed only if its front matter has `source-project` set to
339 `gitlab-org/cli`. If every `glab/` in both locations is glab-installed,
340 run `glab skills update glab` from the project. It replaces all of them.
341 Otherwise, refresh only the glab-installed ones with
342 `glab skills install glab --force` from that project (add `--global`
343 for the user location). Ask the user about any copy without
344 `source-project`.
345 - Installed with `--path`: run
346 `glab skills install glab --path <parent-dir> --force`.
347 - Third-party copy: refresh it at its source.
3483. If the problem is still present on `main`, confirm with the user, then open
349 a merge request against `source-project` with the fix. Keep changes
350 focused: one fix per merge request, with a Conventional Commits message.
Diagnostics10 git calls · 283 ms
CallStatusSizeTime0283 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:02001.8 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=1857
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1857
git.pkt.payload.max=1830
git.sideband.band1.bytes=1830
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1830
git.pack.trailer=fb03183b7909876778f740d196d7516811003517
Open pack map
fetchtree:0200370 B · hit6 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=6
git.response.bytes=370
git.response.cache=HIT
git.response.duration_ms=6
git.fetch.filter=tree:0
git.fetch.wants=290ae7a62f76e23cbbd60697570f19b90ddcece6
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=370
git.pkt.payload.max=343
git.sideband.band1.bytes=343
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=343
git.pack.trailer=0795a26d2b25022c69da2ef2e68cfb92a77ef4bb
Open pack map
fetchtree:0200172 B · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=172
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=tree:0
git.fetch.wants=1d776c45e9ce17714f94b096cf4965ac6cec85d5
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=172
git.pkt.payload.max=145
git.sideband.band1.bytes=145
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=145
git.pack.trailer=4366d9320a915cc228b00c299374927ba2a6e519
Open pack map
fetchtree:0200132 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=132
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=56b988ad01c82fb902f0db541844708590763fc3
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=132
git.pkt.payload.max=105
git.sideband.band1.bytes=105
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=105
git.pack.trailer=127c983927de543aaade2a59ae5622d6a8775441
Open pack map
fetchtree:0200106 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=106
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=32facd9e188c8760a21e463f14a56a62b786e3ed
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=106
git.pkt.payload.max=79
git.sideband.band1.bytes=79
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=79
git.pack.trailer=c950e475b4adf7645af796b1448fa1c1af8c07e1
Open pack map
fetch2005.8 KiB257 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=257
git.response.bytes=5894
git.response.cache=MISS
git.response.duration_ms=257
git.fetch.wants=6d19968b7294e515f6052fc8feed5ab54cc58295
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=5894
git.pkt.payload.max=5867
git.sideband.band1.bytes=5867
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e35415391f994c
Request
2e852a81…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format