GitLab Skill

You are a specialized assistant for managing repositories and CI/CD in GitLab. This skill enables querying projects, merge requests, pipelines, and searching code.

When to Use This Skill

Activate this skill when the user:

Asks about GitLab projects or repositories
Wants to see merge requests or pipelines
Needs to search code or files
Asks about CI/CD status or job logs
Wants to browse repository contents
Mentions "GitLab", "MR", "pipeline", or "CI/CD"

Prerequisites

Before using this skill, ensure:

The ~/.claude/.env file exists with GITLAB_API_TOKEN
Python 3.x is installed
Network access to GitLab instance (https://gitlab.lan.athonet.com)

Skill Structure

.claude/skills/gitlab/
├── SKILL.md                    # This file
├── requirements.txt            # Python dependencies
└── scripts/
    ├── gitlab_client.py        # Core GitLab REST API client
    └── gitlab_helper.py        # High-level repository operations

Project root contains:

~/.claude/.env - API credentials (GITLAB_API_TOKEN)

Quick Start

Using GitLabHelper (Recommended)

import sys
sys.path.insert(0, '.claude/skills/gitlab/scripts')

from gitlab_helper import GitLabHelper

helper = GitLabHelper()
helper.connect()

# List projects
projects = helper.list_projects(membership=True)

# Get a specific project
project = helper.get_project("group/project-name")

# Get file content
content = helper.get_file_content("group/project", "README.md", ref="main")

# List files in repository
files = helper.list_files("group/project", path="src/", recursive=True)

# Get recent commits
commits = helper.get_commits("group/project", branch="main", limit=10)

# List open merge requests
mrs = helper.list_merge_requests(project_path="group/project", state="opened")

# Get my MRs
my_mrs = helper.get_my_merge_requests()

# List pipelines
pipelines = helper.list_pipelines("group/project", status="success")

# Get pipeline jobs
jobs = helper.get_pipeline_jobs("group/project", pipeline_id=12345)

# Get job log
log = helper.get_job_log("group/project", job_id=67890)

# Search code
results = helper.search_code("function_name", project_path="group/project")

Using GitLabClient Directly

import sys
sys.path.insert(0, '.claude/skills/gitlab/scripts')

from gitlab_client import GitLabClient

client = GitLabClient()
client.authenticate()

# Get current user
user = client.get_current_user()

# Get projects
projects = client.get_projects(membership=True, per_page=20)

# Get project by path
project = client.get_project_by_path("group/project")

# Get branches
branches = client.get_branches("group/project")

# Get tags
tags = client.get_tags("group/project")

# Get file content
content = client.get_file_content("group/project", "src/main.py", ref="main")

# Get repository tree
tree = client.get_tree("group/project", path="src/", recursive=True)

# Get merge requests
mrs = client.get_merge_requests(project_id="group/project", state="opened")

# Get pipelines
pipelines = client.get_pipelines("group/project", status="running")

# Global search
results = client.search("query", scope="blobs", project_id="group/project")

Available Operations

GitLabHelper Methods

Method	Description
`connect()`	Initialize GitLab API client with credentials
`list_projects(search, owned, membership, starred)`	List accessible projects
`get_project(project_path)`	Get project by path
`search_projects(query)`	Search for projects
`get_file_content(project, path, ref)`	Get file content
`list_files(project, path, ref, recursive)`	List repository files
`get_branches(project)`	Get project branches
`get_tags(project)`	Get project tags
`get_commits(project, branch)`	Get recent commits
`list_merge_requests(project, state)`	List merge requests
`get_merge_request(project, iid)`	Get single MR
`get_my_merge_requests()`	Get MRs authored by me
`get_assigned_merge_requests()`	Get MRs assigned to me
`list_pipelines(project, status, ref)`	List pipelines
`get_pipeline(project, id)`	Get single pipeline
`get_pipeline_jobs(project, pipeline_id)`	Get pipeline jobs
`get_job_log(project, job_id)`	Get job log
`get_latest_pipeline(project, ref)`	Get latest pipeline
`list_issues(project, state, labels)`	List issues
`search_code(query, project)`	Search code

GitLabClient Methods

Method	Description
`authenticate()`	Load credentials and verify API access
`get_current_user()`	Get authenticated user
`get_projects(search, owned, membership, starred)`	Get projects
`get_project(project_id)`	Get project by ID
`get_project_by_path(path)`	Get project by path
`get_branches(project_id, search)`	Get branches
`get_branch(project_id, branch)`	Get single branch
`get_tags(project_id, search)`	Get tags
`get_commits(project_id, ref_name, since, until)`	Get commits
`get_commit(project_id, sha)`	Get single commit
`get_file(project_id, file_path, ref)`	Get file info
`get_file_content(project_id, file_path, ref)`	Get raw file content
`get_tree(project_id, path, ref, recursive)`	Get repository tree
`get_merge_requests(project_id, state, scope)`	Get merge requests
`get_merge_request(project_id, mr_iid)`	Get single MR
`get_merge_request_changes(project_id, mr_iid)`	Get MR diff
`get_issues(project_id, state, labels)`	Get issues
`get_issue(project_id, issue_iid)`	Get single issue
`get_pipelines(project_id, status, ref)`	Get pipelines
`get_pipeline(project_id, pipeline_id)`	Get single pipeline
`get_pipeline_jobs(project_id, pipeline_id)`	Get pipeline jobs
`get_job_log(project_id, job_id)`	Get job log
`get_groups(search, owned)`	Get groups
`get_group(group_id)`	Get single group
`get_group_projects(group_id, include_subgroups)`	Get group projects
`search(query, scope, project_id, group_id)`	Global search

Common Tasks

1. Check Pipeline Status

# Get latest pipeline for a branch
pipeline = helper.get_latest_pipeline("group/project", ref="main")
print(f"Pipeline #{pipeline.id}: {pipeline.status}")

# Get failed jobs
if pipeline.status == "failed":
    jobs = helper.get_pipeline_jobs("group/project", pipeline.id)
    for job in jobs:
        if job["status"] == "failed":
            print(f"Failed: {job['name']} in stage {job['stage']}")
            log = helper.get_job_log("group/project", job["id"])
            print(log[-1000:])  # Last 1000 chars

2. Review Merge Requests

# Get open MRs assigned to me
mrs = helper.get_assigned_merge_requests()
for mr in mrs:
    print(f"!{mr.iid}: {mr.title}")
    print(f"  {mr.source_branch} -> {mr.target_branch}")
    print(f"  Author: {mr.author}")
    print(f"  URL: {mr.web_url}")

3. Browse Repository

# List files in a directory
files = helper.list_files("group/project", path="src/", ref="main")
for f in files:
    print(f"{'[D]' if f['type'] == 'tree' else '[F]'} {f['name']}")

# Read a file
content = helper.get_file_content("group/project", "src/config.py", ref="main")
print(content)

4. Search Code

# Search for a function across projects
results = helper.search_code("authenticate_user")
for r in results:
    print(f"{r['path']} in project {r['project_id']}")
    print(f"  {r['data'][:100]}...")

5. Check Recent Activity

# Get recent commits
commits = helper.get_commits("group/project", branch="main", limit=5)
for c in commits:
    print(f"{c['id']} - {c['title']} ({c['author']})")

# Get recent tags
tags = helper.get_tags("group/project", limit=5)
for t in tags:
    print(f"{t['name']} - {t['message']}")

Error Handling

Common errors and solutions:

Error	Cause	Solution
401 Unauthorized	Invalid token	Check GITLAB_TOKEN in .env
403 Forbidden	No project access	Request project permissions
404 Not Found	Project/MR doesn't exist	Verify project path
SSL Error	Self-signed certificate	Set verify_ssl=False (default)

Running Scripts

# Run the helper example
python .claude/skills/gitlab/scripts/gitlab_helper.py

# Run client directly with search
python .claude/skills/gitlab/scripts/gitlab_client.py --search "project-name"

Configuration

The client reads settings from environment:

GITLAB_API_TOKEN - Personal Access Token required
GITLAB_URL - GitLab instance URL (default: https://gitlab.lan.athonet.com)

Creating a Personal Access Token

Go to GitLab → User Settings → Access Tokens
Create token with scopes: api, read_api, read_repository
Add to ~/.claude/.env: GITLAB_API_TOKEN=glpat-xxxxxxxxxxxx

API Limits

Maximum 100 results per page
Rate limits apply per GitLab instance configuration
Large file downloads may timeout