GitLab Repository Access Skill for Claude

A performant, secure skill enabling Claude to interact with GitLab repositories.

Version: 1.1.0

Features

• ✅ Public Repository Support - Access public repos without authentication
• ✅ Private Repository Support - Full access with PAT authentication
• ✅ Repository Validation - Confirm repository exists and is accessible
• ✅ Full Repository Context - Get metadata, languages, and structure
• ✅ File Tree Traversal - Navigate complete repository structure
• ✅ Single & Batch File Reading - Efficient file content retrieval
• ✅ Branch Management - List, compare, and navigate branches
• ✅ Commit History - View recent commits and changes
• ✅ File Search - Find files by name pattern

File Structure

This skill uses a flat file structure for simplicity:

gitlab-skill/
├── SKILL.md           # Skill documentation (Claude reads this)
├── README.md          # This file
├── gitlab_client.py   # Core API client
├── gitlab_cli.py      # CLI interface
└── test_gitlab.py     # Unit tests

Requirements

• Python 3.8+
• No external dependencies (uses stdlib only)
• GitLab Personal Access Token with read_repository and read_api scopes (for private repos)

Installation

Option 1: Download a Release (Recommended)

Download the latest release from the Releases page. Each release includes:

• gitlab_client.py - Core API client
• gitlab_cli.py - CLI interface
• SKILL.md - Generated documentation for Claude
• README.md - This documentation
• LICENSE - MIT License

Extract to your Claude skills directory:

/mnt/skills/user/gitlab/

Option 2: Clone the Repository

git clone https://gitlab.com/YawLighthouse/claude-gitlab-connection-skill.git
cd claude-gitlab-connection-skill

# Generate the SKILL.md file
python generate_skill.py --output SKILL.md

Option 3: Download SKILL.md from CI/CD Artifacts

The SKILL.md file is automatically generated on every push to the main branch. To download it:

1. Go to CI/CD → Pipelines
2. Click on the latest successful pipeline
3. Find the generate-skill-md job in the build stage
4. Click on the job, then click Browse under Job artifacts
5. Download SKILL.md

Or use the GitLab API:

# Download the latest SKILL.md artifact
curl --output SKILL.md \
  "https://gitlab.com/YawLighthouse/claude-gitlab-connection-skill/-/jobs/artifacts/main/raw/SKILL.md?job=generate-skill-md"

Why SKILL.md is Generated

The SKILL.md file is not stored in the repository. Instead, it's generated automatically by generate_skill.py during CI/CD. This ensures:

• Documentation always matches the current code
• Version numbers are injected automatically
• Release packages are self-contained

Quick Start

1. Public Repositories (No Token Required)

# Validate access
python gitlab_cli.py validate YawLighthouse/claude-gitlab-connection-skill

# Get info
python gitlab_cli.py info YawLighthouse/claude-gitlab-connection-skill

# Get file tree
python gitlab_cli.py tree YawLighthouse/claude-gitlab-connection-skill

# Read a file
python gitlab_cli.py file YawLighthouse/claude-gitlab-connection-skill README.md

2. Private Repositories (Token Required)

Get a GitLab Personal Access Token:

1. Go to GitLab → Settings → Access Tokens
2. Create token with scopes: read_repository, read_api
3. Copy the token (starts with glpat-)

# Validate access
python gitlab_cli.py --token glpat-xxx validate user/private-repo

# Get info
python gitlab_cli.py --token glpat-xxx info user/private-repo

# Read files
python gitlab_cli.py --token glpat-xxx files user/private-repo "README.md,src/main.py"

3. Run Tests

# Unit tests
python test_gitlab.py

# Integration tests (requires token for private repos)
python test_gitlab.py --integration --project YawLighthouse/claude-gitlab-connection-skill
python test_gitlab.py --integration --token glpat-xxx --project user/private-repo

CLI Commands

Command	Description
validate	Check repository access
info	Get repository metadata
tree	Get file structure
file	Get single file content
files	Batch retrieve multiple files (faster!)
branches	List all branches
branch	Get branch details
search	Search files by name
commits	Get recent commits
compare	Compare two branches
help	Show command help

Output Formats

• --format md (default) - Human-readable Markdown
• --format json - Machine-parseable JSON

Claude Shorthand Commands

Claude can use shorthand commands:

gl:validate YawLighthouse/claude-gitlab-connection-skill
gl:info YawLighthouse/claude-gitlab-connection-skill  
gl:tree user/repo TOKEN
gl:file user/repo src/main.py TOKEN
gl:files user/repo "a.py,b.py" TOKEN develop

Changelog

v1.1.0

• Added public repository support (no token required)
• Improved error messages with helpful hints
• Fixed bug where ref parameter was required for file operations
• Simplified to flat file structure
• Added repository info caching for performance
• Added CI/CD pipeline with automated testing
• Added automated release generation

v1.0.0

• Initial release

Creating a Release

Releases are automated via GitLab CI/CD. To create a new release:

# Tag the release
git tag v1.2.0

# Push the tag
git push origin v1.2.0

The pipeline will automatically:

1. Run all tests
2. Generate SKILL.md documentation
3. Create release packages (.tar.gz and .zip)
4. Publish to GitLab Package Registry
5. Create a GitLab Release with download links

Platform Support

Currently supports gitlab.com only. Self-hosted GitLab instances are not supported.

CI/CD Pipeline

This project uses GitLab CI/CD for automated testing:

Stage	Jobs	Description
lint	syntax-check, flake8	Code quality checks
test	unit-tests, integration-tests, python-3.9/3.10/3.12	Automated testing
security	bandit-security, secrets-check	Security scanning
report	pages	Coverage reports on GitLab Pages

All merge requests must pass the CI pipeline before merging.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Security

• Token passed per-request, never stored
• All connections use HTTPS
• Minimum required scopes recommended

License

MIT License - Use freely.