GitLab CLI (glab)

Rules

• ALWAYS verify auth before first command: glab auth status
• ALWAYS use -R owner/repo when not inside the target git repo
• For self-hosted GitLab, set GITLAB_HOST or use --hostname
• Use --output=json when parsing output programmatically
• NEVER hardcode tokens in commands — use glab auth login or GITLAB_TOKEN env var
• Pagination params go in URL, not flags: glab api "projects/:id/jobs?per_page=100" (NOT --per-page)
• When creating MRs, ALWAYS add --remove-source-branch --squash-before-merge unless the user explicitly says otherwise

Auth

glab auth login                                    # Interactive
glab auth login --hostname gitlab.example.org      # Self-hosted
glab auth status                                   # Verify

MR Workflow

git push -u origin feature-branch
glab mr create --title "Fix bug" --description "Closes #123" \
  --remove-source-branch --squash-before-merge --reviewer=alice,bob
glab mr list --reviewer=@me                        # MRs to review
glab mr checkout 42                                # Test locally
glab mr approve 42
glab mr merge 42 --remove-source-branch

Issue Workflow

glab issue create --title "Bug" --label=bug --assignee=@me
glab issue list --assignee=@me
glab issue close 123 -m "Fixed in MR !42"

CI/CD

glab ci status                    # Current pipeline status
glab ci status --live             # Watch until pipeline completes
glab pipeline ci view             # Watch pipeline (interactive)
glab ci trace                     # View job logs
glab ci lint                      # Validate .gitlab-ci.yml
glab ci run                       # Trigger pipeline
glab ci retry                     # Retry failed pipeline

Wait for pipeline in scripts (glab has no built-in blocking wait):

while true; do
  status=$(glab api "projects/:id/pipelines?ref=$(git branch --show-current)&per_page=1" \
    | jq -r '.[0].status')
  case "$status" in
    success) echo "Pipeline passed"; break ;;
    failed|canceled) echo "Pipeline $status"; exit 1 ;;
    *) echo "Status: $status, waiting..."; sleep 15 ;;
  esac
done

Auto-merge when pipeline succeeds:

glab mr merge <MR_ID> --when-pipeline-succeeds

API

glab api projects/:id/merge_requests
glab api --paginate "projects/:id/pipelines/123/jobs?per_page=100"
glab api --method POST projects/:id/issues --field title="Bug"

Quick Fixes

Error	Fix
401 Unauthorized	glab auth login
404 Project Not Found	Check repo name + access permissions
not a git repository	cd to repo or use -R owner/repo
source branch already has MR	glab mr list to find existing
pipeline must succeed	glab ci status then fix/retry

References

• references/commands.md — Full command reference (MR, Issue, CI/CD, Repo, API, Labels, Releases, Variables, etc.)
• references/pipeline-debug.md — Pipeline 排查流程、Job 日志、重试/取消、Artifacts、批量清理
• references/config.md — 认证管理、多实例、环境变量、配置文件、Shell 补全、Aliases
• references/troubleshooting.md — Auth, network, SSL, config 常见错误和解决方案