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 clientgitlab_cli.py - CLI interfaceSKILL.md - Generated documentation for ClaudeREADME.md - This documentationLICENSE - 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:
- Go to CI/CD → Pipelines
- Click on the latest successful pipeline
- Find the generate-skill-md job in the build stage
- Click on the job, then click Browse under Job artifacts
- 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:
- Go to GitLab → Settings → Access Tokens
- Create token with scopes:
read_repository, read_api
- 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 |
--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
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:
- Run all tests
- Generate
SKILL.md documentation
- Create release packages (
.tar.gz and .zip)
- Publish to GitLab Package Registry
- Create a GitLab Release with download links
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.