glab

name	glab
description	Use this skill when the user asks to work with GitLab from the terminal, especially with `glab`: merge requests, issues, pipelines, releases, project metadata, or GitLab API calls. Prefer it when a local checkout is already connected to GitLab and `glab` is a better fit than manual browser work or raw `curl`.

glab CLI

Use glab when the task is about GitLab state, not just local Git state. In a Git worktree, glab can infer host and project context from remotes, so run commands from the relevant repository root when possible.

Start from the official English docs and the installed CLI help, not memory. glab changes over time.

Core Workflow

Every glab task should follow this pattern:

1. Confirm repo and auth context.
2. Check the source-derived command tree or local help before guessing flags.
3. Prefer the highest-level glab subcommand that already fits the task.
4. Fall back to glab api only when the CLI does not expose the needed operation or data.
5. Keep commands non-interactive and scriptable when automation matters.

Workflow

1. Confirm repository and auth context.

   • Run git rev-parse --show-toplevel and git remote -v when repo targeting matters.
   • Run glab auth status when access, host, or token scope may matter.

2. Read references before guessing flags.

   • Start with references/docs-command-tree.md for the source-derived command and subcommand tree.
   • Use the split usage references when exact Usage lines or documented Options matter: references/usage/core.md, references/usage/mr.md, references/usage/issue.md, references/usage/ci.md, references/usage/release.md, references/usage/repo.md, references/usage/misc.md.
   • Use references/official-command-map.md as a local CLI snapshot for quick verification.

3. Prefer the highest-level glab command that already exists.

   • Use glab mr, glab issue, glab ci, glab release, and similar purpose-built groups first.
   • Use glab api only when the high-level CLI does not expose the operation or response shape you need.

4. Verify against local help when precision matters.

   • Check glab <group> --help or glab <group> <subcommand> --help.
   • If the installed binary differs from docs, state that explicitly instead of improvising.
   • Do not invent flags. Check the documented Usage and Options first.

5. Keep output scriptable.

   • Prefer non-interactive flags in automation.
   • For API-heavy workflows, prefer glab api ... --output ndjson and post-process with jq when needed.

Common Requests

• "List my open merge requests."
• "Show the merge request for this branch."
• "Approve MR 123."
• "Add a note to MR 123 saying it needs a rebase."
• "List open issues in this project."
• "Create an issue for this bug."
• "Show the latest failed pipeline."
• "Retry job 12345."
• "Lint the current .gitlab-ci.yml."
• "List releases for this project."
• "Create a release for tag v1.2.3."
• "Use glab api to fetch project variables."
• "Run a GraphQL query against GitLab."

When Not To Use

• Do not use this skill for local-only Git operations that git already handles better.
• Do not use this skill when the task does not require GitLab state, metadata, or API access.
• Do not jump to glab api if a purpose-built glab subcommand already exists.

Essential Commands

# Context
git rev-parse --show-toplevel
git remote -v
glab auth status

# Merge requests
glab mr list
glab mr view <id>
glab mr diff <id>
glab mr create --fill
glab mr approve <id>
glab mr note <id> -m "message"
glab mr merge <id>

# Issues
glab issue list
glab issue view <id>
glab issue create
glab issue update <id>
glab issue note <id> -m "message"

# CI/CD
glab ci status
glab ci list
glab ci get
glab ci lint
glab ci trace <job-id>
glab ci retry <job-id>
glab ci trigger <job-id>

# Releases
glab release list
glab release view <tag>
glab release create <tag>
glab release upload <tag> <files...>

# API fallback
glab api projects/:fullpath/releases
glab api graphql -f query='query { currentUser { username } }'
glab api issues --paginate --output ndjson

Common Patterns

Outside Repository Context

When not running inside a Git repository, pass -R/--repo explicitly.

glab mr list -R group/project
glab issue list -R group/project
glab ci list -R group/project

Self-Hosted GitLab

If the target is not gitlab.com, verify auth and host selection before running project commands.

glab auth status
glab auth login --hostname gitlab.example.com
glab mr list -R gitlab.example.com/group/project

Automation and JSON Output

For scripts and automation, prefer non-interactive commands and machine-readable output.

NO_PROMPT=true glab mr list --output json
glab mr list --output json | jq '.[].title'
glab api issues --paginate --output ndjson

API Fallback

Use glab api only when a built-in subcommand does not expose the data or operation you need.

glab api projects/:fullpath/variables
glab api "projects/:id/jobs?per_page=100" --paginate
glab api graphql -f query='query { currentUser { username } }'

Command Selection

Merge requests

• Inspect: glab mr list, glab mr view <id>, glab mr diff <id>
• Create: glab mr create --fill
• Update: glab mr update <id>
• Review: glab mr approve <id>, glab mr note <id> -m "..."
• Integrate: glab mr merge <id>

Issues

• Inspect: glab issue list, glab issue view <id>
• Create: glab issue create
• Update: glab issue update <id>
• Comment: glab issue note <id> -m "..."

CI/CD

• Current pipeline: glab ci status, glab ci view
• Enumerate pipelines: glab ci list
• Machine-readable pipeline data: glab ci get
• Validate config: glab ci lint
• Logs: glab ci trace <job-id>
• Retry or trigger: glab ci retry <job-id>, glab ci trigger <job-id>

Releases

• Inspect: glab release list, glab release view <tag>
• Create or update: glab release create <tag>
• Assets: glab release upload <tag> <files...>, glab release download <tag>

Generic API access

Use glab api when:

• the high-level command is missing
• you need fields the built-in command does not show
• you need GraphQL
• you need pagination or exact request control

Useful patterns:

• REST: glab api projects/:fullpath/releases
• GraphQL: glab api graphql -f query='query { currentUser { username } }'
• Pagination: glab api issues --paginate --output ndjson

Repository placeholders such as :fullpath, :repo, and :branch resolve from the current repository context.

Practical Rules

• Prefer running glab in the target repo root so project and host detection work.
• Avoid interactive prompts in scripts; pass flags or environment variables.
• If auth or host selection is unclear, inspect glab auth status and consider --hostname or -R/--repo.
• For unsupported workflows, use glab api instead of dropping straight to curl.
• If a command fails, re-check docs and local help before assuming the flag exists.