Glab

GitLab CLI (glab) Skill

Provides guidance for using glab, the official GitLab CLI, to perform GitLab operations from the terminal.

When to Use This Skill

Invoke when the user needs to:

• Create, review, or manage merge requests
• Work with GitLab issues
• Monitor or trigger CI/CD pipelines
• Clone or manage repositories
• Perform any GitLab operation from the command line

Prerequisites

Verify glab installation before executing commands:

glab --version

If not installed, inform the user and provide platform-specific installation guidance.

Authentication Quick Start

Most glab operations require authentication:

# Interactive authentication
glab auth login

# Check authentication status
glab auth status

# For self-hosted GitLab
glab auth login --hostname gitlab.example.org

# Using environment variables
export GITLAB_TOKEN=your-token
export GITLAB_HOST=gitlab.example.org  # for self-hosted

Core Workflows

Creating a Merge Request

# 1. Ensure branch is pushed
git push -u origin feature-branch

# 2. Create MR
glab mr create --title "Add feature" --description "Implements X"

# With reviewers and labels
glab mr create --title "Fix bug" --reviewer=alice,bob --label="bug,urgent"

Reviewing Merge Requests

# 1. List MRs awaiting your review
glab mr list --reviewer=@me

# 2. Checkout MR locally to test
glab mr checkout <mr-number>

# 3. After testing, approve
glab mr approve <mr-number>

# 4. Add review comments
glab mr note <mr-number> -m "Please update tests"

Managing Issues

# Create issue with labels
glab issue create --title "Bug in login" --label=bug

# Link MR to issue
glab mr create --title "Fix login" --description "Closes #<issue-number>"

# List your assigned issues
glab issue list --assignee=@me

Monitoring CI/CD

# Watch pipeline in progress
glab pipeline ci view

# Check pipeline status
glab ci status

# View logs if failed
glab ci trace

# Retry failed pipeline
glab ci retry

# Lint CI config before pushing
glab ci lint

Common Patterns

Working Outside Repository Context

When not in a Git repository, specify the repository:

glab mr list -R owner/repo
glab issue list -R owner/repo

Self-Hosted GitLab

Set hostname for all commands:

export GITLAB_HOST=gitlab.example.org
# or per-command
glab repo clone gitlab.example.org/owner/repo

Automation and Scripting

Use JSON output for parsing:

glab mr list --output=json | jq '.[] | .title'

Using the API Command

The glab api command provides direct GitLab API access:

# Basic API call
glab api projects/:id/merge_requests

# IMPORTANT: Pagination uses query parameters in URL, NOT flags
# ❌ WRONG: glab api --per-page=100 projects/:id/jobs
# ✓ CORRECT: glab api "projects/:id/jobs?per_page=100"

# Auto-fetch all pages
glab api --paginate "projects/:id/pipelines/123/jobs?per_page=100"

# POST with data
glab api --method POST projects/:id/issues --field title="Bug" --field description="Details"

Best Practices

1. Verify authentication before executing commands: glab auth status 2. Use `--help` to explore command options: glab <command> --help 3. Link MRs to issues using "Closes #123" in MR description 4. Lint CI config before pushing: glab ci lint 5. Check repository context when commands fail: git remote -v

Common Commands Quick Reference

Merge Requests:

• glab mr list --assignee=@me - Your assigned MRs
• glab mr list --reviewer=@me - MRs for you to review
• glab mr create - Create new MR
• glab mr checkout <number> - Test MR locally
• glab mr approve <number> - Approve MR
• glab mr merge <number> - Merge approved MR

Issues:

• glab issue list - List all issues
• glab issue create - Create new issue
• glab issue close <number> - Close issue

CI/CD:

• glab pipeline ci view - Watch pipeline
• glab ci status - Check status
• glab ci lint - Validate .gitlab-ci.yml
• glab ci retry - Retry failed pipeline

Repository:

• glab repo clone owner/repo - Clone repository
• glab repo view - View repo details
• glab repo fork - Fork repository

Progressive Disclosure

For detailed command documentation, refer to:

• references/commands-detailed.md - Comprehensive command reference with all flags and options
• references/quick-reference.md - Condensed command cheat sheet
• references/troubleshooting.md - Detailed error scenarios and solutions

Load these references when:

• User needs specific flag or option details
• Troubleshooting authentication or connection issues
• Working with advanced features (API, schedules, variables, etc.)

Common Issues Quick Fixes

"command not found: glab" - Install glab or verify PATH

"401 Unauthorized" - Run glab auth login

"404 Project Not Found" - Verify repository name and access permissions

"not a git repository" - Navigate to repo or use -R owner/repo flag

"source branch already has a merge request" - Use glab mr list to find existing MR

For detailed troubleshooting, load references/troubleshooting.md.

Notes

• glab auto-detects repository context from Git remote
• Most commands have --web flag to open in browser
• Use --output=json for scripting and automation
• Multiple GitLab accounts can be authenticated simultaneously
• Commands respect Git configuration and current repository context

Changelog

All notable changes to the glab skill for Claude Code will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.0] - 2025-11-05

Added

• Initial release of the glab skill for Claude Code
• Comprehensive SKILL.md with detailed command documentation
• Coverage of core glab commands:
• Authentication (glab auth)
• Merge Requests (glab mr)
• Issues (glab issue)
• CI/CD (glab ci, glab pipeline)
• Repository operations (glab repo)
• API access (glab api)
• Labels, Releases, Snippets, Users
• Common workflow patterns:
• Feature branch and MR workflow
• Code review process
• CI/CD pipeline monitoring
• Issue tracking and linking
• Best practices and troubleshooting guidance
• Quick reference guide in references/quick-reference.md
• Comprehensive README.md with installation and usage instructions
• CONTRIBUTING.md with contribution guidelines
• MIT License
• .gitignore for common development artifacts

Features

• Tool restrictions (allowed-tools: Bash, Read, Grep, Glob)
• Support for both GitLab.com and self-hosted instances
• Environment variable configuration (GITLAB_TOKEN, GITLAB_HOST)
• Multi-instance authentication support
• 30+ documented glab commands
• Real-world usage examples throughout

Documentation

• Complete command reference with examples
• Common flags and options explained
• Project context detection guidance
• Configuration management instructions
• Error messages and solutions

[1.1.0] - 2025-11-06

Changed - Progressive Disclosure Refactoring

Major restructuring following Claude Code Skills best practices:

• SKILL.md reduced from 471 to 203 lines - Now focused on core workflows and patterns
• Implemented three-level context loading:

1. SKILL.md frontmatter for discovery 2. SKILL.md body for core workflows (loaded when invoked) 3. references/ folder for detailed docs (loaded only as needed)

Added

• references/commands-detailed.md (610 lines) - Comprehensive command reference with all flags and options
• references/troubleshooting.md (669 lines) - Detailed error scenarios, causes, and solutions

Improved

• SKILL.md now workflow-first, teaching WHEN and HOW to use glab
• README now explains progressive disclosure architecture
• references/quick-reference.md remains as condensed cheat sheet (145 lines)

Why This Matters

• Faster skill invocation - Smaller initial context load
• Better performance - Claude loads detailed docs only when needed
• Clearer guidance - Workflows over command memorization
• Scalable architecture - Easy to add more detailed references

Migration Notes

Users should re-pull or re-clone the skill to get the new structure:

cd ~/.claude/skills/glab && git pull
# or
rm -rf ~/.claude/skills/glab && git clone <repo> ~/.claude/skills/glab

[Unreleased]

Planned

• Additional examples for advanced workflows
• More coverage of glab duo AI features
• Enterprise GitLab feature documentation
• Integration patterns with CI/CD tools
• Scripts for common operations

Notes

• This skill is based on glab v1.40.0+ command structure
• Tested with Claude Code Skills specification
• Designed following progressive disclosure principles
• Written in imperative/infinitive style as per Claude Code best practices

---

For the complete list of changes, see the commit history.

Contributing to the glab Skill

Thank you for your interest in improving the GitLab CLI skill for Claude Code! This document provides guidelines for contributing.

How to Contribute

Reporting Issues

If you find errors, missing commands, or unclear instructions:

1. Check if the issue already exists in the issue tracker 2. Provide specific details about the problem 3. Include the glab version you're using (glab --version) 4. Include examples of commands that don't work as documented

Suggesting Improvements

We welcome suggestions for:

• Additional glab commands to document
• New workflow patterns
• Better examples
• Clearer explanations
• Additional troubleshooting scenarios

Making Changes

1. Test First: Always test commands with actual glab CLI before documenting 2. Follow the Style: Match the existing writing style (imperative/infinitive form) 3. Include Examples: Provide practical, working examples 4. Update References: If adding major sections, update the quick-reference guide

Style Guidelines

Writing Style

Follow the established imperative/infinitive form:

• ✅ "To create a merge request, use: glab mr create"
• ❌ "You can create a merge request by using glab mr create"

Code Examples

• Always use proper markdown code fencing with bash syntax highlighting
• Include comments for complex commands
• Show expected output when relevant
• Test all examples before committing

Organization

The SKILL.md is organized as: 1. YAML frontmatter - Metadata (name, description, allowed-tools) 2. Introduction - What the skill provides 3. When to Use - Invocation scenarios 4. Prerequisites - Setup requirements 5. Core Commands - Organized by feature area 6. Workflows - Complete usage patterns 7. Best Practices - Guidance and recommendations 8. Troubleshooting - Common issues and solutions

When adding content, place it in the appropriate section.

Testing Changes

Before submitting changes:

1. Verify YAML frontmatter is valid:

• name is lowercase with hyphens only
• description is clear and under 1024 characters
• allowed-tools list is appropriate

2. Test commands with actual glab CLI:

   # Verify glab is installed
   glab --version

   # Test commands you've documented
   glab <command> --help

3. Check markdown formatting:

• Code blocks are properly fenced
• Lists are consistently formatted
• Links work correctly

4. Verify skill loads in Claude Code:

• Place skill in .claude/skills/glab/
• Restart Claude Code
• Test skill invocation

What to Update

When making changes, consider updating:

• SKILL.md - Main skill instructions
• quick-reference.md - If adding major commands
• README.md - If changing installation or usage
• CHANGELOG.md - Document your changes

Commit Guidelines

Write clear commit messages:

• ✅ "Add glab duo commands documentation"
• ✅ "Fix incorrect flag for glab mr create"
• ✅ "Update authentication examples"
• ❌ "Update stuff"
• ❌ "Fix"

Command Coverage

Currently Documented

The skill currently covers:

• Authentication (glab auth)
• Merge Requests (glab mr)
• Issues (glab issue)
• CI/CD (glab ci, glab pipeline)
• Repositories (glab repo)
• API (glab api)
• Labels, Releases, Snippets, Users

Could Use More Coverage

Areas that could be expanded:

• glab duo - GitLab Duo AI features
• glab cluster - Kubernetes cluster management
• glab iteration - Iteration management
• glab stack - Stack management
• glab opentofu - OpenTofu integration
• Advanced API usage patterns
• Enterprise GitLab features

Documentation Standards

Command Documentation Template

When documenting a new command, use this structure:

### Command Category

#### Basic Usage

Simple command

glab command subcommand

With common flags

glab command subcommand --flag=value

#### Common Options
- `--flag1` - Description
- `--flag2` - Description

#### Examples

Example 1: Description

glab command subcommand --example

Example 2: Description

glab command subcommand --another-example

Getting Help

If you have questions: 1. Check the glab official documentation 2. Use glab <command> --help 3. Review existing skill documentation patterns 4. Open an issue for discussion

Review Process

Changes will be reviewed for:

• Accuracy of commands and flags
• Clarity of explanations
• Consistency with existing style
• Practical value to users
• Proper testing

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Resources

• glab Official Repository
• GitLab CLI Documentation
• Claude Code Skills Documentation
• Agent Skills Specification

Thank you for helping make this skill better! 🚀

GitLab CLI (glab) Skill for Claude Code

A comprehensive Claude Code skill that provides expert guidance for using the GitLab CLI (glab) to manage GitLab resources directly from the command line.

Overview

This skill enables Claude Code to effectively assist with GitLab workflows using the official glab CLI tool. It provides detailed knowledge about GitLab operations including merge requests, issues, CI/CD pipelines, repository management, and more.

What This Skill Provides

• Core workflows: Common GitLab operations (MRs, issues, CI/CD, repos)
• Authentication guidance: Quick setup for GitLab.com and self-hosted instances
• Best practices: When and how to use glab effectively
• Progressive disclosure: Concise core instructions with detailed references loaded as needed
• Comprehensive references: Detailed command docs, troubleshooting, and quick reference guides

Installation

Installing the Skill

This skill should be placed in your Claude Code skills directory:

# For project-specific installation
mkdir -p .claude/skills
git clone https://github.com/henricook/claude-glab-skill .claude/skills/glab

# For personal/global installation
mkdir -p ~/.claude/skills
git clone https://github.com/henricook/claude-glab-skill ~/.claude/skills/glab

After installation, your directory structure will be:

.claude/skills/glab/
├── SKILL.md                          # Core skill (~200 lines, loaded when skill invoked)
├── references/                       # Detailed docs (loaded only as needed)
│   ├── commands-detailed.md          # Comprehensive command reference
│   ├── quick-reference.md            # Command cheat sheet
│   └── troubleshooting.md            # Detailed error scenarios
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE

Installing glab CLI

Before using this skill, ensure glab is installed on your system:

macOS:

brew install glab

Linux:

# Debian/Ubuntu
sudo apt install glab

# Fedora/RHEL
sudo dnf install glab

# Arch Linux
sudo pacman -S glab

Windows:

# Using Chocolatey
choco install glab

# Using Scoop
scoop install glab

From source:

go install gitlab.com/gitlab-org/cli/cmd/glab@latest

For more installation options, visit: https://gitlab.com/gitlab-org/cli

Usage

Once installed, Claude Code will automatically detect when you need GitLab CLI assistance and can invoke this skill. You can also explicitly invoke it:

@claude using the glab skill, help me create a merge request

Or simply ask Claude Code to perform GitLab operations:

Can you list my open merge requests?
Create an issue for the bug we just found
Show me the status of the CI pipeline

Skill Architecture

This skill follows the progressive disclosure design principle for optimal performance:

Three-Level Context Loading

1. SKILL.md frontmatter (~50 chars) - Loaded first for skill discovery and invocation 2. SKILL.md body (~200 lines) - Core workflows and patterns loaded when skill is invoked 3. references/ folder - Detailed documentation loaded into context only as needed

SKILL.md (Core Instructions)

The main skill file is concise and focused on:

• When to use glab for different tasks
• Essential authentication setup
• Common workflow patterns (not exhaustive command lists)
• Best practices and quick fixes
• References to detailed documentation

Why it's concise: Loads quickly when invoked, providing immediate guidance without overwhelming context.

references/ (Detailed Documentation)

commands-detailed.md - Load when:

• User needs specific flag or option details
• Working with advanced commands (API, variables, schedules)
• Need comprehensive command examples

troubleshooting.md - Load when:

• Encountering authentication or connection errors
• Debugging CI/CD pipeline issues
• Need detailed error scenarios and solutions

quick-reference.md - Load when:

• User wants a command cheat sheet
• Quick lookup of common flags and patterns

Tool Restrictions

The skill is configured with allowed-tools: Bash, Read, Grep, Glob to ensure Claude Code can:

• Execute glab commands via Bash
• Read configuration and reference files as needed
• Search for relevant files and patterns
• Work within the repository context

Skill Features

Workflow-First Approach

Rather than memorizing commands, the skill teaches:

• Creating merge requests with reviewers and labels
• Reviewing code by checking out MRs locally
• Managing issues and linking them to MRs
• Monitoring CI/CD pipelines and handling failures

Comprehensive Command Coverage

30+ glab commands documented across:

• Merge Requests, Issues, CI/CD Pipelines
• Repositories, API access, Labels, Releases
• Snippets, Users, Variables, SSH Keys
• And more (see references/commands-detailed.md)

Context-Aware Assistance

The skill helps Claude Code:

• Detect when authentication is needed
• Identify repository context issues
• Suggest appropriate flags and options
• Load detailed docs only when necessary

Self-Hosted GitLab Support

Full support for GitLab.com and self-hosted instances with environment variable configuration and multi-instance authentication.

Examples

After installation, Claude Code can help with tasks like:

Creating a merge request:

Create a merge request for my current branch with the title "Fix login bug" and assign it to reviewers alice and bob

Reviewing merge requests:

Show me all merge requests where I'm assigned as a reviewer

Managing CI/CD:

Watch the current pipeline and let me know if it passes

Working with issues:

Create a bug issue titled "API timeout" with high priority label

Configuration

The skill automatically adapts to:

• Current repository context
• Authenticated GitLab instances
• Self-hosted GitLab via GITLAB_HOST environment variable
• Multiple authentication profiles

Contributing

This skill is designed to be comprehensive and up-to-date. If you find commands or workflows that should be added, please contribute:

1. Test your additions with actual glab usage 2. Follow the imperative/infinitive writing style established in SKILL.md 3. Include practical examples 4. Update this README if adding major new sections

Requirements

• Claude Code with Skills support
• glab CLI tool installed and in PATH
• Authenticated GitLab account (via glab auth login)
• Git repository context for repository-specific operations

Troubleshooting

If Claude Code doesn't recognize the skill: 1. Verify the skill is in .claude/skills/glab/ or ~/.claude/skills/glab/ 2. Ensure SKILL.md exists and has valid YAML frontmatter 3. Restart Claude Code if necessary

If glab commands fail: 1. Verify installation: glab --version 2. Check authentication: glab auth status 3. Ensure you're in a Git repository or use -R owner/repo flag

Resources

• glab Official Repository: https://gitlab.com/gitlab-org/cli
• GitLab CLI Documentation: https://docs.gitlab.com/editor_extensions/gitlab_cli/
• Claude Code Skills: https://docs.claude.com/en/docs/claude-code/skills

License

This skill is provided as a community resource for Claude Code users working with GitLab.

Version

Version: 1.0.0 Last Updated: November 2025 Compatible with: glab v1.40.0+

glab Commands - Detailed Reference

This is a comprehensive reference for all glab commands. This file is loaded when detailed command information is needed.

Merge Requests (MR)

Listing Merge Requests

# List MRs assigned to you
glab mr list --assignee=@me

# List MRs where you're a reviewer
glab mr list --reviewer=@me

# List all open MRs
glab mr list

# Filter by state
glab mr list --state=merged
glab mr list --state=closed
glab mr list --state=all

Creating Merge Requests

# Create MR from current branch (interactive)
glab mr create

# Create MR with title and description
glab mr create --title "Fix bug" --description "Fixes issue #123"

# Create MR for specific issue
glab mr create 123

# Create draft MR
glab mr create --draft

# Create MR and assign reviewers
glab mr create --reviewer=username1,username2

# Create MR with labels
glab mr create --label="bug,priority:high"

# Create MR with assignee
glab mr create --assignee=username

# Create MR to a specific target branch
glab mr create --target-branch=develop

# Create MR and remove source branch after merge
glab mr create --remove-source-branch

Viewing and Interacting with MRs

# View MR details (opens in browser by default)
glab mr view 123

# View MR in terminal
glab mr view 123 --web=false

# View MR with comments
glab mr view 123 --comments

# Checkout MR branch locally
glab mr checkout 243

# Approve MR
glab mr approve 123

# Unapprove MR
glab mr unapprove 123

# Merge MR
glab mr merge 123

# Merge and delete source branch
glab mr merge 123 --remove-source-branch

# Close MR without merging
glab mr close 123

# Reopen closed MR
glab mr reopen 123

# Add note/comment to MR
glab mr note 123 -m "Looks good to me"

# Update MR title
glab mr update 123 --title "New title"

# Update MR description
glab mr update 123 --description "New description"

# Mark MR as draft
glab mr update 123 --draft

# Mark MR as ready (remove draft status)
glab mr update 123 --ready

# Subscribe to MR notifications
glab mr subscribe 123

# Unsubscribe from MR notifications
glab mr unsubscribe 123

Issues

Listing Issues

# List all issues
glab issue list

# List issues assigned to you
glab issue list --assignee=@me

# List issues with specific label
glab issue list --label=bug

# List issues with multiple labels
glab issue list --label="bug,priority:high"

# List closed issues
glab issue list --state=closed

# List all issues (open and closed)
glab issue list --state=all

# Search issues
glab issue list --search="login error"

# List issues assigned to specific user
glab issue list --assignee=username

Creating and Managing Issues

# Create issue interactively
glab issue create

# Create issue with title and description
glab issue create --title "Bug in login" --description "Users cannot log in"

# Create issue with labels
glab issue create --title "Feature request" --label="enhancement,feature"

# Create issue with assignee
glab issue create --title "Fix bug" --assignee=username

# Create confidential issue
glab issue create --title "Security issue" --confidential

# View issue details
glab issue view 456

# View issue in browser
glab issue view 456 --web

# Close issue
glab issue close 456

# Close with a comment
glab issue close 456 -m "Fixed in MR !123"

# Reopen issue
glab issue reopen 456

# Update issue title
glab issue update 456 --title "New title"

# Update issue description
glab issue update 456 --description "New description"

# Add labels to issue
glab issue update 456 --label="bug,confirmed"

# Assign issue
glab issue update 456 --assignee=username

# Subscribe to issue
glab issue subscribe 456

# Unsubscribe from issue
glab issue unsubscribe 456

CI/CD Pipelines

Viewing Pipelines

# Watch pipeline in progress (interactive)
glab pipeline ci view

# List recent pipelines
glab ci list

# List pipelines with specific status
glab ci list --status=failed
glab ci list --status=success
glab ci list --status=running

# View specific pipeline status
glab ci status

# View pipeline for specific branch
glab ci status --branch=main

# Get pipeline trace/logs
glab ci trace

# Get trace for specific job
glab ci trace <job-id>

# View pipeline details
glab ci view <pipeline-id>

# Delete a pipeline
glab ci delete <pipeline-id>

Triggering and Managing Pipelines

# Run/trigger pipeline
glab ci run

# Run pipeline for specific branch
glab ci run --branch=develop

# Run pipeline with variables
glab ci run --variables-file /tmp/variables.json

# Run pipeline with inline variables
glab ci run -V KEY1=value1 -V KEY2=value2

# Retry failed pipeline
glab ci retry

# Retry specific pipeline
glab ci retry <pipeline-id>

# Cancel running pipeline
glab ci cancel

# Cancel specific pipeline
glab ci cancel <pipeline-id>

CI Configuration

# Lint .gitlab-ci.yml file in current directory
glab ci lint

# Lint specific file
glab ci lint --path=.gitlab-ci.yml

# View CI configuration
glab ci config

# Get CI job artifacts
glab ci artifact <job-id>

# Download artifacts to specific path
glab ci artifact <job-id> -p path/to/download

Repository Operations

Cloning Repositories

# Clone repository
glab repo clone namespace/project

# Clone to specific directory
glab repo clone namespace/project target-dir

# Clone from self-hosted GitLab
GITLAB_HOST=gitlab.example.org glab repo clone groupname/project

# Clone repository by group (interactive)
glab repo clone -g groupname

# Clone with specific protocol
glab repo clone namespace/project --protocol=ssh
glab repo clone namespace/project --protocol=https

Repository Information and Management

# View repository details
glab repo view

# View specific repository
glab repo view owner/repo

# View in browser
glab repo view --web

# Fork repository
glab repo fork

# Fork to specific namespace
glab repo fork --clone --namespace=mygroup

# Archive repository
glab repo archive owner/project

# Unarchive repository
glab repo unarchive owner/project

# Delete repository
glab repo delete owner/project

# Create repository
glab repo create project-name

# Create private repository
glab repo create project-name --private

# Create repository with description
glab repo create project-name --description "My project"

# Mirror repository
glab repo mirror source-repo target-repo

API Access

Making API Calls

# GET request
glab api projects/:id/merge_requests

# GET with specific project ID
glab api projects/12345/merge_requests

# POST request with data
glab api --method POST projects/:id/issues --field title="Bug report"

# POST with multiple fields
glab api --method POST projects/:id/issues \
  --field title="Bug" \
  --field description="Description here" \
  --field labels="bug,priority:high"

# PUT request
glab api --method PUT projects/:id/merge_requests/1 --field title="New Title"

# DELETE request
glab api --method DELETE projects/:id/issues/123

# Paginated API request (auto-fetches all pages)
glab api --paginate projects/:id/issues

# Pagination with query parameters (specify per_page in URL)
glab api "projects/:id/issues?per_page=100"

# Combine pagination flag with query parameters
glab api --paginate "projects/:id/merge_requests?per_page=50&state=opened"

# Manual pagination (specific page)
glab api "projects/:id/issues?page=2&per_page=100"

# Include response headers
glab api --include projects/:id

# Silent mode (no progress)
glab api --silent projects/:id/merge_requests

Labels

# List all labels
glab label list

# Create label
glab label create "bug" --color="#FF0000"

# Create label with description
glab label create "feature" --color="#00FF00" --description "New features"

# Delete label
glab label delete "old-label"

Releases

# List releases
glab release list

# Create release
glab release create v1.0.0

# Create release with notes
glab release create v1.0.0 --notes "Release notes here"

# Create release from file
glab release create v1.0.0 --notes-file CHANGELOG.md

# Create release with assets
glab release create v1.0.0 --asset-links='[{"name":"Asset","url":"https://..."}]'

# View specific release
glab release view v1.0.0

# Download release assets
glab release download v1.0.0

# Delete release
glab release delete v1.0.0

Snippets

# List snippets
glab snippet list

# List all snippets (including private)
glab snippet list --all

# Create snippet
glab snippet create --title "Config" --filename config.yml

# Create snippet from file
glab snippet create --title "Script" myfile.sh

# Create private snippet
glab snippet create --title "Secret" --private secret.txt

# View snippet
glab snippet view <snippet-id>

# Delete snippet
glab snippet delete <snippet-id>

User Operations

# View current user information
glab user view

# View specific user
glab user view username

# List user's events
glab user events

# List specific user's events
glab user events username

Variables (CI/CD)

# List variables
glab variable list

# Get specific variable
glab variable get VAR_NAME

# Set/create variable
glab variable set VAR_NAME value

# Set protected variable
glab variable set VAR_NAME value --protected

# Set masked variable
glab variable set VAR_NAME value --masked

# Update variable
glab variable update VAR_NAME new-value

# Delete variable
glab variable delete VAR_NAME

# Export variables
glab variable export > variables.json

# Import variables
glab variable import < variables.json

Additional Commands

Aliases

# Create alias
glab alias set co "mr checkout"

# List aliases
glab alias list

# Delete alias
glab alias delete co

SSH Keys

# List SSH keys
glab ssh-key list

# Add SSH key
glab ssh-key add ~/.ssh/id_rsa.pub

# Add SSH key with title
glab ssh-key add ~/.ssh/id_rsa.pub --title "Work laptop"

# Delete SSH key
glab ssh-key delete <key-id>

Deploy Keys

# List deploy keys
glab deploy-key list

# Add deploy key
glab deploy-key add --title "CI/CD" --key "ssh-rsa ..."

# Delete deploy key
glab deploy-key delete <key-id>

Schedules (Pipeline Schedules)

# List pipeline schedules
glab schedule list

# Create schedule
glab schedule create --cron "0 2 * * *" --ref main --description "Nightly build"

# Run schedule immediately
glab schedule run <schedule-id>

# Delete schedule
glab schedule delete <schedule-id>

Common Flags Across Commands

Most glab commands support these common flags:

• --help, -h - Show help for command
• --repo, -R - Specify repository (format: OWNER/REPO)
• --web, -w - Open in web browser
• --output, -o - Output format (json, text, etc.)
• --verbose - Enable verbose output
• --page, -p - Page number for paginated results
• --per-page, -P - Number of items per page

Output Formats

Many commands support different output formats:

# JSON output (useful for scripting)
glab mr list --output=json

# Pipe to jq for processing
glab mr list --output=json | jq '.[] | .title'

Configuration Commands

# View all configuration
glab config get

# Get specific config value
glab config get editor

# Set configuration value
glab config set editor vim

# Common config keys:
# - editor: preferred text editor
# - browser: web browser to use
# - glamour_style: style for terminal rendering
# - host: default GitLab host

Completion

# Generate completion script for bash
glab completion --shell bash

# For zsh
glab completion --shell zsh

# For fish
glab completion --shell fish

# For PowerShell
glab completion --shell powershell

# Install completion (bash example)
glab completion --shell bash > /etc/bash_completion.d/glab

Version and Updates

# Show glab version
glab version

# Check for updates
glab check-update

# View changelog
glab changelog

glab Quick Reference Guide

A condensed reference for the most commonly used GitLab CLI commands.

Authentication

glab auth login                    # Interactive login
glab auth status                   # Check auth status
echo "token" | glab auth login --stdin  # Login with token

Merge Requests

# Listing
glab mr list                       # All open MRs
glab mr list --assignee=@me        # MRs assigned to me
glab mr list --reviewer=@me        # MRs for me to review

# Creating
glab mr create                     # Interactive creation
glab mr create --title "Fix" --description "Desc"
glab mr create --draft             # Create draft MR
glab mr create --reviewer=alice,bob

# Viewing & Managing
glab mr view 123                   # View MR #123
glab mr checkout 123               # Checkout MR branch
glab mr approve 123                # Approve MR
glab mr merge 123                  # Merge MR
glab mr note 123 -m "Comment"      # Add comment

Issues

# Listing
glab issue list                    # All issues
glab issue list --assignee=@me     # Assigned to me
glab issue list --label=bug        # With label

# Creating & Managing
glab issue create                  # Interactive
glab issue create --title "Bug" --label=bug
glab issue view 456                # View issue
glab issue close 456               # Close issue

CI/CD

# Pipelines
glab pipeline ci view              # Watch pipeline
glab ci list                       # List pipelines
glab ci status                     # Pipeline status
glab ci trace                      # View logs

# Running & Managing
glab ci run                        # Trigger pipeline
glab ci lint                       # Lint .gitlab-ci.yml
glab ci retry                      # Retry pipeline
glab ci cancel                     # Cancel pipeline

Repository

glab repo clone org/project        # Clone repository
glab repo view                     # View repo details
glab repo fork                     # Fork repository

API

glab api projects/:id/merge_requests           # GET request
glab api --method POST projects/:id/issues \
  --field title="Bug"              # POST with data

Common Flags

--help, -h                         # Show help
--repo, -R owner/repo              # Specify repository
--web, -w                          # Open in browser
--output, -o json                  # JSON output
--verbose                          # Verbose output

Environment Variables

GITLAB_TOKEN=xxx                   # API token
GITLAB_HOST=gitlab.example.org     # Self-hosted GitLab

Configuration

glab config get                    # View configuration
glab config set key value          # Set config value

Complete Command List

• glab alias - Create command shortcuts
• glab api - Make API calls
• glab auth - Authentication management
• glab changelog - Generate changelogs
• glab check-update - Check for updates
• glab ci - CI/CD operations
• glab cluster - Kubernetes cluster management
• glab completion - Shell completion
• glab config - Configuration management
• glab deploy-key - Deploy key management
• glab duo - GitLab Duo AI features
• glab incident - Incident management
• glab issue - Issue tracking
• glab iteration - Iteration management
• glab job - CI job operations
• glab label - Label management
• glab mr - Merge request operations
• glab opentofu - OpenTofu integration
• glab release - Release management
• glab repo - Repository operations
• glab schedule - Pipeline schedule management
• glab securefile - Secure file management
• glab snippet - Snippet operations
• glab ssh-key - SSH key management
• glab stack - Stack management
• glab token - Access token management
• glab user - User operations
• glab variable - CI/CD variable management
• glab version - Show version

Tips

1. Use glab <command> --help for detailed help 2. Commands auto-detect repository context from git remote 3. Use -R owner/repo when outside a repository 4. Most commands have --web flag to open in browser 5. Use --output=json for scripting 6. Enable completion: glab completion --shell bash

glab Troubleshooting Guide

Comprehensive troubleshooting guide for common glab CLI issues and errors.

Installation Issues

Command Not Found

Error:

command not found: glab

or

glab: command not found

Causes:

• glab is not installed
• glab is not in PATH

Solutions: 1. Verify installation:

   which glab

2. Install glab if missing (see main README for installation instructions)

3. If installed but not in PATH, add to PATH:

   # Find where glab is installed
   find / -name glab 2>/dev/null

   # Add to PATH in ~/.bashrc or ~/.zshrc
   export PATH="$PATH:/path/to/glab"

4. For Go installation, ensure $GOPATH/bin is in PATH:

   export PATH="$PATH:$(go env GOPATH)/bin"

Version Conflicts

Error:

glab: incompatible version

Solution: Update to the latest version:

# macOS
brew upgrade glab

# Linux (depends on package manager)
sudo apt update && sudo apt upgrade glab

Authentication Issues

401 Unauthorized

Error:

failed to get current user: GET https://gitlab.com/api/v4/user: 401 {message: 401 Unauthorized}

Causes:

• Not authenticated
• Token expired
• Invalid token
• Wrong GitLab instance

Solutions: 1. Authenticate:

   glab auth login

2. Check authentication status:

   glab auth status

3. Re-authenticate with new token:

   glab auth login --hostname gitlab.com --token YOUR_TOKEN

4. Verify token has correct scopes (api, read_user, write_repository)

5. For self-hosted GitLab, ensure correct hostname:

   glab auth login --hostname gitlab.example.org

Token Permissions

Error:

403 Forbidden

or

insufficient permissions

Causes:

• Token lacks required scopes
• User doesn't have project permissions

Solutions: 1. Create new token with required scopes:

• api
• read_api
• read_user
• write_repository
• read_repository

2. Verify project access in GitLab web UI

3. Check if project is private and token has access

Multiple Accounts

Issue: Working with multiple GitLab instances

Solution: glab supports multiple authenticated accounts:

# Authenticate with gitlab.com
glab auth login --hostname gitlab.com

# Authenticate with self-hosted instance
glab auth login --hostname gitlab.example.org

# Check all authenticated accounts
glab auth status

# Use specific host for command
glab mr list -R gitlab.example.org/namespace/project

Repository Context Issues

Not a Git Repository

Error:

fatal: not a git repository (or any of the parent directories): .git

Causes:

• Running glab outside a Git repository
• Git repository not initialized

Solutions: 1. Navigate to a Git repository:

   cd /path/to/your/repo

2. Or specify repository explicitly:

   glab mr list -R owner/repo

3. Initialize Git repository if needed:

   git init
   git remote add origin git@gitlab.com:owner/repo.git

Wrong Repository Detected

Issue: glab operating on wrong repository

Solution: 1. Check current repository remote:

   git remote -v

2. Specify correct repository:

   glab mr list -R owner/correct-repo

3. Update Git remote if wrong:

   git remote set-url origin git@gitlab.com:owner/correct-repo.git

404 Project Not Found

Error:

404 Project Not Found

Causes:

• Repository doesn't exist
• Wrong namespace/project name
• No access permissions
• Wrong GitLab instance

Solutions: 1. Verify repository name:

   # Check in GitLab web UI
   # Correct format: namespace/project

2. Check you have access to the project

3. Verify GitLab instance:

   glab auth status

4. For self-hosted, set correct host:

   GITLAB_HOST=gitlab.example.org glab repo view

Merge Request Issues

Source Branch Already Has MR

Error:

failed to create merge request: source branch already has a merge request

Cause:

• A merge request already exists for this branch

Solutions: 1. List existing MRs to find it:

   glab mr list
   glab mr list --source-branch=$(git branch --show-current)

2. View the existing MR:

   glab mr view <mr-number>

3. Update existing MR instead of creating new one:

   glab mr update <mr-number> --title "New title"

Cannot Merge: Conflicts Exist

Error:

Cannot merge: merge conflicts exist

Solutions: 1. Checkout MR locally:

   glab mr checkout <mr-number>

2. Fetch latest target branch:

   git fetch origin main

3. Merge or rebase:

   git merge origin/main
   # or
   git rebase origin/main

4. Resolve conflicts and push:

   git add .
   git commit
   git push

Pipeline Must Succeed

Error:

cannot merge: pipeline must succeed

Cause:

• Project requires successful pipeline before merge
• Pipeline is failing or pending

Solutions: 1. Check pipeline status:

   glab ci status

2. View pipeline details:

   glab pipeline ci view

3. Fix pipeline failures and retry:

   glab ci retry

4. If project settings allow, force merge (not recommended):

   # Only if you have maintainer permissions
   glab mr merge <mr-number> --when-pipeline-succeeds

Cannot Push to Source Branch

Error:

You cannot push commits to this source branch

Cause:

• MR is from a fork
• No write access to source repository

Solution: Ask MR author to make changes, or: 1. Checkout MR:

   glab mr checkout <mr-number>

2. Make changes on their fork (requires special permissions)

Pipeline/CI Issues

Pipeline Not Found

Error:

pipeline not found

Causes:

• No pipeline exists for current branch
• Pipeline hasn't started yet

Solutions: 1. Trigger a pipeline:

   glab ci run

2. Check if .gitlab-ci.yml exists:

   ls -la .gitlab-ci.yml

3. Verify CI/CD is enabled in project settings

CI Lint Errors

Error:

.gitlab-ci.yml is invalid

Solutions: 1. Lint locally:

   glab ci lint

2. Common issues:

• YAML syntax errors (tabs vs spaces)
• Invalid job names
• Missing required fields
• Incorrect indentation

3. Use GitLab CI/CD config validation in web UI

4. Check GitLab CI/CD documentation for syntax

Cannot Download Artifacts

Error:

failed to download artifacts

Causes:

• Artifacts expired
• Job didn't produce artifacts
• Permission issues

Solutions: 1. Check if job has artifacts:

   glab ci view <pipeline-id>

2. Verify artifacts haven't expired (check project settings)

3. Run job again if needed:

   glab ci retry

Network and Connection Issues

Connection Timeout

Error:

dial tcp: i/o timeout

Causes:

• Network connectivity issues
• Firewall blocking connection
• GitLab instance down

Solutions: 1. Check network connection:

   ping gitlab.com

2. Verify GitLab status:

   curl -I https://gitlab.com

3. Check firewall/proxy settings

4. For self-hosted, verify hostname:

   ping gitlab.example.org

SSL Certificate Issues

Error:

x509: certificate signed by unknown authority

Causes:

• Self-signed certificate
• Corporate proxy
• Invalid SSL certificate

Solutions: 1. For development/testing only (NOT production):

   export GIT_SSL_NO_VERIFY=true

2. Add certificate to system trust store (preferred)

3. Configure Git to use specific CA bundle:

   git config --global http.sslCAInfo /path/to/cert.pem

Environment Variable Issues

GITLAB_HOST Not Recognized

Issue: Commands still using gitlab.com instead of self-hosted instance

Solutions: 1. Export variable in current shell:

   export GITLAB_HOST=gitlab.example.org

2. Add to shell profile (~/.bashrc, ~/.zshrc):

   echo 'export GITLAB_HOST=gitlab.example.org' >> ~/.bashrc
   source ~/.bashrc

3. Or use flag for each command:

   glab mr list -R gitlab.example.org/owner/repo

GITLAB_TOKEN Not Working

Issue: Token set but authentication still failing

Solutions: 1. Verify token is exported:

   echo $GITLAB_TOKEN

2. Ensure no spaces in token:

   export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

3. Token should not be quoted in export:

   # Correct
   export GITLAB_TOKEN=glpat-xxx

   # Incorrect
   export GITLAB_TOKEN="glpat-xxx"

4. Verify token is valid in GitLab web UI

Output and Display Issues

Garbled or Missing Output

Issue: Terminal output is corrupted or incomplete

Solutions: 1. Disable glamour styling:

   export GLAMOUR_STYLE=notty

2. Use plain text output:

   glab mr list --output=text

3. Update terminal emulator

4. Try different pager:

   export PAGER=less

JSON Parsing Errors

Issue: Cannot parse JSON output

Solutions: 1. Ensure command supports JSON:

   glab mr list --output=json

2. Pipe through jq for validation:

   glab mr list --output=json | jq '.'

3. Check for error messages mixed with JSON

Performance Issues

Commands Running Slowly

Causes:

• Large repository
• Many results being fetched
• Network latency

Solutions: 1. Limit results:

   glab mr list --per-page=10 --page=1

2. Use specific filters:

   glab mr list --assignee=@me --state=opened

3. Disable web browser opening:

   glab mr view 123 --web=false

Configuration Issues

Config File Corruption

Error:

failed to load config

Solutions: 1. Check config file:

   cat ~/.config/glab-cli/config.yml

2. Backup and recreate:

   mv ~/.config/glab-cli/config.yml ~/.config/glab-cli/config.yml.bak
   glab auth login

3. Manually edit config:

   vim ~/.config/glab-cli/config.yml

General Troubleshooting Steps

When encountering any error:

1. Check version:

   glab version

2. Update glab:

   glab check-update

3. Enable verbose output:

   glab <command> --verbose

4. Check authentication:

   glab auth status

5. Verify repository context:

   git remote -v

6. Use --help:

   glab <command> --help

7. Check GitLab API status: Visit https://status.gitlab.com

8. Review logs:

   # Check recent commands
   history | grep glab

Getting Additional Help

If issues persist:

1. Check glab documentation: https://docs.gitlab.com/editor_extensions/gitlab_cli/ 2. Search glab issues: https://gitlab.com/gitlab-org/cli/-/issues 3. Create a new issue with:

• glab version
• Operating system
• Full error message
• Steps to reproduce
• Output with --verbose flag