glab

어떤 스킬인가요?

Expert guidance for using the GitLab CLI (glab) to manage GitLab issues, merge requests, CI/CD pipelines, repositories, and other GitLab operations from the command line. Use this skill when the user needs to interact with GitLab resources or perform GitLab workflows.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

---
name: glab
description: Expert guidance for using the GitLab CLI (glab) to manage GitLab issues, merge requests, CI/CD pipelines, repositories, and other GitLab operations from the command line. Use this skill when the user needs to interact with GitLab resources or perform GitLab workflows.
allowed-tools: Bash, Read, Grep, Glob
---

# 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:
```bash
glab --version
```

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

## Authentication Quick Start

Most glab operations require authentication:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:
```bash
glab mr list -R owner/repo
glab issue list -R owner/repo
```

### Self-Hosted GitLab

Set hostname for all commands:
```bash
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:
```bash
glab mr list --output=json | jq '.[] | .title'
```

### Using the API Command

The `glab api` command provides direct GitLab API access:

```bash
# 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

# Editor files
.vscode/
.idea/
*.swp
*.swo
*~

# OS files
.DS_Store
Thumbs.db

# Temporary files
*.tmp
*.log

# Node modules (if any scripts use Node.js)
node_modules/

# Python cache (if any scripts use Python)
__pycache__/
*.pyc
*.pyo
*.pyd

# Testing artifacts
test-output/

# 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:
   ```bash
   # 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:

```markdown
### Command Category

#### Basic Usage
```bash
# Simple command
glab command subcommand

# With common flags
glab command subcommand --flag=value
```

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

#### Examples
```bash
# 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](https://docs.gitlab.com/editor_extensions/gitlab_cli/)
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](https://gitlab.com/gitlab-org/cli)
- [GitLab CLI Documentation](https://docs.gitlab.com/editor_extensions/gitlab_cli/)
- [Claude Code Skills Documentation](https://docs.claude.com/en/docs/claude-code/skills)
- [Agent Skills Specification](https://github.com/anthropics/skills/blob/main/agent_skills_spec.md)

Thank you for helping make this skill better! 🚀

# 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](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [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:
```bash
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](../../commits/main).

# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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
```bash
# Create alias
glab alias set co "mr checkout"

# List aliases
glab alias list

# Delete alias
glab alias delete co
```

### SSH Keys
```bash
# 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
```bash
# 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)
```bash
# 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:

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

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

## Configuration Commands

```bash
# 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

```bash
# 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

```bash
# Show glab version
glab version

# Check for updates
glab check-update

# View changelog
glab changelog
```

MIT License

Copyright (c) 2025 Claude Code Skills Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

# 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:

```bash
# 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:**
```bash
brew install glab
```

**Linux:**
```bash
# Debian/Ubuntu
sudo apt install glab

# Fedora/RHEL
sudo dnf install glab

# Arch Linux
sudo pacman -S glab
```

**Windows:**
```powershell
# Using Chocolatey
choco install glab

# Using Scoop
scoop install glab
```

**From source:**
```bash
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 Quick Reference Guide

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

## Authentication

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

## Merge Requests

```bash
# 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

```bash
# 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

```bash
# 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

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

## API

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

## Common Flags

```bash
--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

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

## Configuration

```bash
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:
   ```bash
   which glab
   ```

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

3. If installed but not in PATH, add to PATH:
   ```bash
   # 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:
   ```bash
   export PATH="$PATH:$(go env GOPATH)/bin"
   ```

### Version Conflicts

**Error:**
```
glab: incompatible version
```

**Solution:**
Update to the latest version:
```bash
# 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:
   ```bash
   glab auth login
   ```

2. Check authentication status:
   ```bash
   glab auth status
   ```

3. Re-authenticate with new token:
   ```bash
   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:
   ```bash
   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:

```bash
# 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:
   ```bash
   cd /path/to/your/repo
   ```

2. Or specify repository explicitly:
   ```bash
   glab mr list -R owner/repo
   ```

3. Initialize Git repository if needed:
   ```bash
   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:
   ```bash
   git remote -v
   ```

2. Specify correct repository:
   ```bash
   glab mr list -R owner/correct-repo
   ```

3. Update Git remote if wrong:
   ```bash
   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:
   ```bash
   # Check in GitLab web UI
   # Correct format: namespace/project
   ```

2. Check you have access to the project

3. Verify GitLab instance:
   ```bash
   glab auth status
   ```

4. For self-hosted, set correct host:
   ```bash
   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:
   ```bash
   glab mr list
   glab mr list --source-branch=$(git branch --show-current)
   ```

2. View the existing MR:
   ```bash
   glab mr view <mr-number>
   ```

3. Update existing MR instead of creating new one:
   ```bash
   glab mr update <mr-number> --title "New title"
   ```

### Cannot Merge: Conflicts Exist

**Error:**
```
Cannot merge: merge conflicts exist
```

**Solutions:**
1. Checkout MR locally:
   ```bash
   glab mr checkout <mr-number>
   ```

2. Fetch latest target branch:
   ```bash
   git fetch origin main
   ```

3. Merge or rebase:
   ```bash
   git merge origin/main
   # or
   git rebase origin/main
   ```

4. Resolve conflicts and push:
   ```bash
   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:
   ```bash
   glab ci status
   ```

2. View pipeline details:
   ```bash
   glab pipeline ci view
   ```

3. Fix pipeline failures and retry:
   ```bash
   glab ci retry
   ```

4. If project settings allow, force merge (not recommended):
   ```bash
   # 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:
   ```bash
   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:
   ```bash
   glab ci run
   ```

2. Check if .gitlab-ci.yml exists:
   ```bash
   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:
   ```bash
   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:
   ```bash
   glab ci view <pipeline-id>
   ```

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

3. Run job again if needed:
   ```bash
   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:
   ```bash
   ping gitlab.com
   ```

2. Verify GitLab status:
   ```bash
   curl -I https://gitlab.com
   ```

3. Check firewall/proxy settings

4. For self-hosted, verify hostname:
   ```bash
   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):
   ```bash
   export GIT_SSL_NO_VERIFY=true
   ```

2. Add certificate to system trust store (preferred)

3. Configure Git to use specific CA bundle:
   ```bash
   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:
   ```bash
   export GITLAB_HOST=gitlab.example.org
   ```

2. Add to shell profile (~/.bashrc, ~/.zshrc):
   ```bash
   echo 'export GITLAB_HOST=gitlab.example.org' >> ~/.bashrc
   source ~/.bashrc
   ```

3. Or use flag for each command:
   ```bash
   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:
   ```bash
   echo $GITLAB_TOKEN
   ```

2. Ensure no spaces in token:
   ```bash
   export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
   ```

3. Token should not be quoted in export:
   ```bash
   # 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:
   ```bash
   export GLAMOUR_STYLE=notty
   ```

2. Use plain text output:
   ```bash
   glab mr list --output=text
   ```

3. Update terminal emulator

4. Try different pager:
   ```bash
   export PAGER=less
   ```

### JSON Parsing Errors

**Issue:** Cannot parse JSON output

**Solutions:**
1. Ensure command supports JSON:
   ```bash
   glab mr list --output=json
   ```

2. Pipe through jq for validation:
   ```bash
   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:
   ```bash
   glab mr list --per-page=10 --page=1
   ```

2. Use specific filters:
   ```bash
   glab mr list --assignee=@me --state=opened
   ```

3. Disable web browser opening:
   ```bash
   glab mr view 123 --web=false
   ```

## Configuration Issues

### Config File Corruption

**Error:**
```
failed to load config
```

**Solutions:**
1. Check config file:
   ```bash
   cat ~/.config/glab-cli/config.yml
   ```

2. Backup and recreate:
   ```bash
   mv ~/.config/glab-cli/config.yml ~/.config/glab-cli/config.yml.bak
   glab auth login
   ```

3. Manually edit config:
   ```bash
   vim ~/.config/glab-cli/config.yml
   ```

## General Troubleshooting Steps

When encountering any error:

1. **Check version:**
   ```bash
   glab version
   ```

2. **Update glab:**
   ```bash
   glab check-update
   ```

3. **Enable verbose output:**
   ```bash
   glab <command> --verbose
   ```

4. **Check authentication:**
   ```bash
   glab auth status
   ```

5. **Verify repository context:**
   ```bash
   git remote -v
   ```

6. **Use --help:**
   ```bash
   glab <command> --help
   ```

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

8. **Review logs:**
   ```bash
   # 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