glab

# GitLab CLI (glab) Official CLI for GitLab. Manage issues, merge requests, pipelines, and more from the terminal. > **Source:** Inspired by [NikiforovAll/glab-skill](https://github.com/NikiforovAll/claude-code-rules/tree/main/plugins/handbook-glab/skills/glab-skill) on Smithery. ## ⚠️ Security Notice **The `glab api` command provides unrestricted GitLab API access with your token.** - A compromised or overly-permissive token can delete projects, modify settings, expose secrets - **Recommendation:** Use tokens with minimal scopes: - `read_api` - Read-only operations - `api` - Full access (only when write operations needed) - For automation, consider project-level tokens with limited scope - Never use tokens with `sudo` scope unless required ## Prerequisites **Required binaries:** - `glab` - GitLab CLI - `jq` - JSON processor (for scripts and API parsing) **Required credentials:** - `GITLAB_TOKEN` - GitLab personal access token **Optional configuration:** - `GITLAB_HOST` - Self-hosted GitLab instance (default: gitlab.com) ```bash # Verify installation glab --version jq --version # Authenticate (interactive) glab auth login # Or via environment export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" export GITLAB_HOST="gitlab.example.org" # for self-hosted # Verify auth glab auth status ``` ## Quick Reference **Merge Requests:** ```bash glab mr create --title "Fix" --description "Closes #123" glab mr list --reviewer=@me # MRs awaiting your review glab mr checkout 123 # Test MR locally glab mr approve 123 && glab mr merge 123 ``` **Issues:** ```bash glab issue create --title "Bug" --label=bug glab issue list --assignee=@me glab issue close 456 ``` **CI/CD:** ```bash glab ci status # Current pipeline status glab pipeline ci view # Watch pipeline live glab ci lint # Validate .gitlab-ci.yml glab ci retry # Retry failed pipeline ``` **Working Outside Repo:** ```bash glab mr list -R owner/repo # Specify repository ``` **Advanced API Access:** See **references/api-advanced.md** for `glab api` usage. This command enables arbitrary GitLab API calls and should be used with appropriately-scoped tokens. ## Core Workflows ### Create and Merge MR ```bash # 1. Push branch git push -u origin feature-branch # 2. Create MR glab mr create --title "Add feature" --description "Implements X" --reviewer=alice,bob --label="enhancement" # 3. After approval, merge glab mr approve 123 glab mr merge 123 --remove-source-branch ``` ### Review MR ```bash # List MRs for review glab mr list --reviewer=@me # Checkout and test glab mr checkout 123 # Approve or comment glab mr approve 123 glab mr note 123 -m "Looks good, just one suggestion..." ``` ### Monitor Pipeline ```bash # Watch current branch pipeline glab pipeline ci view # Check specific pipeline glab ci view 456 # View failed job logs glab ci trace # Retry glab ci retry ``` ## Self-Hosted GitLab ```bash # Set default host export GITLAB_HOST=gitlab.example.org # Or per-command glab mr list -R gitlab.example.org/owner/repo ``` ## Scripts | Script | Description | |--------|-------------| | `glab-mr-await.sh` | Wait for MR approval and successful pipeline | | `glab-pipeline-watch.sh` | Monitor pipeline with exit codes for CI | ```bash # Wait for MR to be approved and merged ./scripts/glab-mr-await.sh 123 --timeout 600 # Watch pipeline, exit 0 on success, 1 on failure ./scripts/glab-pipeline-watch.sh --timeout 300 ``` **Script environment variables:** - `TIMEOUT` - Max wait time in seconds (default varies by script) - `INTERVAL` - Polling interval in seconds (default 5-10s) ## Troubleshooting | Error | Fix | |-------|-----| | `command not found: glab` | Install glab | | `command not found: jq` | Install jq | | `401 Unauthorized` | Set `GITLAB_TOKEN` or run `glab auth login` | | `404 Project Not Found` | Verify repo name and permissions | | `not a git repository` | Use `-R owner/repo` flag | | `source branch already has MR` | `glab mr list` to find existing | For detailed troubleshooting, see **references/troubleshooting.md**. ## Progressive Disclosure - **references/api-advanced.md** - `glab api` usage with security considerations - **references/commands-detailed.md** - Full command reference with all flags - **references/troubleshooting.md** - Detailed error scenarios and solutions Load these when you need specific flag details or are debugging issues. ## Best Practices 1. Always verify auth: `glab auth status` 2. Use minimal-scope tokens for read operations 3. Link MRs to issues: "Closes #123" in description 4. Lint CI config before pushing: `glab ci lint` 5. Use `--output=json` for scripting 6. Most commands have `--web` to open in browser