cerngitlab-cli

Category: Docs & Knowledge | Uploader: MohamedElashri | Downloads: 0 | Version: v1.0（Latest）

Search, browse, and analyze CERN GitLab repositories for HEP code, documentation, and examples. Use this skill whenever the user mentions CERN GitLab, LHCb/ATLAS/CMS code, HEP software stacks, or wants to find code patterns, inspect build systems, read READMEs, search issues, or explore releases in gitlab.cern.ch projects. Also trigger when the user references specific CERN projects like DaVinci, Allen, Athena, Gauss, Moore, Boole, or any gitlab.cern.ch URL.

Changelog: Source: GitHub https://github.com/MohamedElashri/cerngitlab-mcp

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 997 B
  - 📄 release.yml 2.1 KB
📁 docs/
- 📄 CHANGELOG.md 3.0 KB
- 📄 dev.md 6.1 KB
📁 icons/
- 📄 icon.png 62.2 KB
- 📄 icon.svg 3.6 KB
- 📄 logo_128.png 11.0 KB
- 📄 logo_256.png 26.6 KB
- 📄 logo_512.png 62.2 KB
- 📄 logo_64.png 4.5 KB
📁 src/
- 📁 cerngitlab_mcp/
  - 📁 cli/
    
    📄 __init__.py 101 B
    
    📄 commands.py 16.1 KB
    
    📄 main.py 1.9 KB
    
    📄 README.md 15.3 KB
  - 📁 tools/
    
    📄 __init__.py 63 B
    
    📄 analyze_dependencies.py 6.0 KB
    
    📄 get_build_config.py 3.2 KB
    
    📄 get_ci_config.py 5.0 KB
    
    📄 get_file_content.py 7.2 KB
    
    📄 get_project_info.py 3.3 KB
    
    📄 get_project_readme.py 3.5 KB
    
    📄 get_release.py 3.1 KB
    
    📄 get_wiki_pages.py 3.7 KB
    
    📄 inspect_project.py 9.1 KB
    
    📄 list_project_files.py 3.3 KB
    
    📄 list_releases.py 2.7 KB
    
    📄 list_tags.py 3.2 KB
    
    📄 search_code.py 11.2 KB
    
    📄 search_issues.py 3.3 KB
    
    📄 search_lhcb_stack.py 3.3 KB
    
    📄 search_projects.py 3.6 KB
    
    📄 utils.py 1.6 KB
  - 📄 __init__.py 116 B
  - 📄 config.py 1.7 KB
  - 📄 exceptions.py 1.4 KB
  - 📄 gitlab_client.py 10.3 KB
  - 📄 logging.py 850 B
  - 📄 py.typed 0 B
  - 📄 server.py 6.0 KB
  - 📄 stack_resolver.py 1.2 KB
📁 tests/
- 📄 __init__.py 0 B
- 📄 conftest.py 1.1 KB
- 📄 test_cli.py 24.8 KB
- 📄 test_integration.py 13.3 KB
- 📄 test_stack_resolver.py 1.4 KB
- 📄 test_tools.py 22.2 KB
📄 .env.example 712 B
📄 .gitignore 194 B
📄 .python-version 5 B
📄 pyproject.toml 1.9 KB
📄 README.md 8.3 KB
📄 SKILL.md 15.5 KB
📄 uv.lock 162.0 KB

SKILL.md

---
name: cerngitlab-cli
description: "Search, browse, and analyze CERN GitLab repositories for HEP code, documentation, and examples. Use this skill whenever the user mentions CERN GitLab, LHCb/ATLAS/CMS code, HEP software stacks, or wants to find code patterns, inspect build systems, read READMEs, search issues, or explore releases in gitlab.cern.ch projects. Also trigger when the user references specific CERN projects like DaVinci, Allen, Athena, Gauss, Moore, Boole, or any gitlab.cern.ch URL."
---

# CERN GitLab CLI

A command-line interface for interacting with CERN GitLab (`gitlab.cern.ch`). Provides 14 tools for searching, browsing, and analyzing HEP code repositories.

The CLI binary is `cerngitlab-cli`. All commands return structured JSON. Public repositories work without authentication; private/internal repos and code search require a token.

## Configuration

Set environment variables prefixed with `CERNGITLAB_`:

| Variable | Default | Description |
|----------|---------|-------------|
| `CERNGITLAB_GITLAB_URL` | `https://gitlab.cern.ch` | GitLab instance URL |
| `CERNGITLAB_TOKEN` | *(empty)* | Personal access token (`read_api` scope) |
| `CERNGITLAB_TIMEOUT` | `30` | HTTP timeout in seconds |
| `CERNGITLAB_MAX_RETRIES` | `3` | Max retries for failed requests |
| `CERNGITLAB_RATE_LIMIT_PER_MINUTE` | `300` | API rate limit |
| `CERNGITLAB_LOG_LEVEL` | `INFO` | Logging level |
| `CERNGITLAB_DEFAULT_REF` | *(empty)* | Default Git branch/tag |

To create a token: visit `https://gitlab.cern.ch/-/user_settings/personal_access_tokens`, create with `read_api` scope, then `export CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx`.

## Authentication

**Most tools work without authentication** for public repositories. However, some features require a personal access token:

### Tools that **require** authentication:
- `search-code` — Global code search across all repositories
- `search-lhcb-stack` — Code search within LHCb software stacks
- `get-wiki` — Access to project wiki pages

### Tools that **may require** authentication:
- `list-releases` — Some projects restrict release API access
- `get-release` — Some projects restrict release API access

### Getting a Token

1. Visit: https://gitlab.cern.ch/-/user_settings/personal_access_tokens
2. Create a new token with the `read_api` scope
3. Export it: `export CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx`

### Checking Auth Status

Use `test-connection` to verify your authentication status:

```bash
cerngitlab-cli test-connection
```

Returns:
```json
{
  "status": "connected",
  "authenticated": false,
  "note": "No token provided — public access only"
}
```

With a token:
```json
{
  "status": "connected",
  "authenticated": true,
  "user": "username"
}
```

## Tool Selection Guide

| Goal | Tool | Auth Required |
|------|------|:---:|
| Find repos by keyword/topic/language | `search-projects` | No |
| Get project metadata & stats | `get-project-info` | No |
| Browse directory tree | `list-files` | No |
| Read a specific file | `get-file` | No |
| Read README (auto-detected) | `get-readme` | No |
| Search code globally | `search-code` | **Yes** |
| Search code in LHCb stack | `search-lhcb-stack` | **Yes** |
| Search issues | `search-issues` | No |
| Access wiki pages | `get-wiki` | **Yes** |
| Full project analysis (build, deps, CI) | `inspect-project` | No |
| List releases | `list-releases` | Sometimes* |
| Get specific release details | `get-release` | Sometimes* |
| List tags (filterable) | `list-tags` | No |
| Test connection & auth status | `test-connection` | No |

> **\* Note:** Some projects may restrict release/tag API access. If you get a 403 error, set `CERNGITLAB_TOKEN`.

## Common Workflows

### Discover repositories

```bash
# Find Python ROOT analysis projects, sorted by stars
cerngitlab-cli search-projects --query "ROOT analysis" --language python --sort-by stars

# Find all LHCb-tagged repositories
cerngitlab-cli search-projects --topic lhcb --per-page 50
```

### Understand a project

```bash
# Get README, file tree, and full project inspection in sequence
cerngitlab-cli get-readme --project lhcb/DaVinci
cerngitlab-cli list-files --project lhcb/DaVinci --path src/
cerngitlab-cli inspect-project --project lhcb/DaVinci
```

`inspect-project` is the most powerful single command — it analyzes build systems, dependencies, CI/CD config, and language breakdown in one call.

### Find code patterns

```bash
# Global code search (requires token)
cerngitlab-cli search-code --search-term "RooFit" --per-page 10

# Search within a specific project
cerngitlab-cli search-code --search-term "PVFinder" --project lhcb/allen

# Search within an LHCb software stack (auto-resolves correct git refs)
cerngitlab-cli search-lhcb-stack --search-term "initialize()" --stack sim11
```

### Track releases and tags

```bash
cerngitlab-cli list-releases --project lhcb/DaVinci
cerngitlab-cli get-release --project lhcb/DaVinci --tag-name v1.2.0
cerngitlab-cli list-tags --project lhcb/DaVinci --search v1
```

## Error Handling

All commands return JSON errors: `{"error": "Error message"}`. Common causes:

- **"Authentication required"** / **"Search API requires authentication"** / **"Wiki access denied"**: Tool needs `CERNGITLAB_TOKEN` but none is set. Set the environment variable with a personal access token (`read_api` scope).
- **"Project not found"** / **"<project_path> not found"**: Wrong project ID or path — verify with `search-projects`. Note: some tools work better with numeric project IDs than `group/project` paths.
- **"GitLab API error (403): 403 Forbidden"**: API access restricted for this project. May require authentication or project is private.
- **"Rate limit exceeded"**: Wait and retry (default: 300 req/min).
- **"File not found"**: Check `--ref` branch and verify path with `list-files`.

---

## Tool Reference

### 1. search-projects

Search for public CERN GitLab projects by keywords, topics, or programming language.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--query` | string | No | - | Matches project name and description |
| `--language` | string | No | - | Filter by language (`python`, `c++`, `fortran`) |
| `--topic` | string | No | - | Filter by topic tag (`physics`, `root`, `lhcb`) |
| `--sort-by` | string | No | `last_activity_at` | `last_activity_at`, `name`, `created_at`, `stars` |
| `--order` | string | No | `desc` | `desc` or `asc` |
| `--per-page` | integer | No | `20` | Results count (1–100) |

**Output:** Array of project objects:
```json
{
  "id": 12345,
  "name": "ProjectName",
  "path_with_namespace": "group/project",
  "description": "...",
  "web_url": "https://gitlab.cern.ch/group/project",
  "default_branch": "main",
  "topics": ["physics", "root"],
  "star_count": 42,
  "forks_count": 15,
  "last_activity_at": "2025-03-10T10:30:00Z",
  "created_at": "2020-01-15T08:00:00Z",
  "visibility": "public"
}
```

---

### 2. get-project-info

Get detailed metadata about a specific project including languages, statistics, and license.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--project` | string | Yes | Project ID or path (e.g., `12345` or `lhcb/allen`) |

**Output:** Single project object with all fields from `search-projects` plus:
```json
{
  "languages": ["Python", "C++"],
  "language_percentages": {"Python": 60.5, "C++": 39.5},
  "open_issues_count": 23,
  "license": "MIT"
}
```

---

### 3. list-files

List files and directories in a project's repository.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--project` | string | Yes | - | Project ID or path |
| `--path` | string | No | `/` | Subdirectory path to list |
| `--ref` | string | No | default branch | Branch/tag/commit |
| `--recursive` | boolean | No | `false` | List recursively |
| `--per-page` | integer | No | `100` | Results count |

**Output:** Array of entries:
```json
{"type": "tree", "path": "src", "name": "src"}
{"type": "blob", "path": "README.md", "name": "README.md"}
```

> **Tip:** If you get a "not found" error with a `group/project` path, try using the numeric project ID instead (found via `search-projects` or `get-project-info`).

---

### 4. get-file

Retrieve the content of a specific file from a repository.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--project` | string | Yes | Project ID or path |
| `--file-path` | string | Yes | Path to file (e.g., `src/main.py`) |
| `--ref` | string | No | Branch/tag/commit |

**Output:**
```json
{
  "file_name": "main.py",
  "file_path": "src/main.py",
  "size": 1234,
  "ref": "main",
  "last_commit_id": "abc123...",
  "content_sha256": "sha256hash...",
  "is_binary": false,
  "content": "#!/usr/bin/env python\n...",
  "language": "python"
}
```

Binary files return `"is_binary": true` and `"content": "[Binary file, N bytes]"`.

---

### 5. get-readme

Get the README content for a project. Automatically finds README.md, .rst, .txt, etc.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--project` | string | Yes | Project ID or path |
| `--ref` | string | No | Branch/tag/commit |

**Output:**
```json
{
  "file_name": "README.md",
  "content": "# Project Title\n\nDescription...",
  "language": "markdown"
}
```

---

### 6. search-code

Search for code snippets across repositories. Returns matching files with line-level context. **Requires authentication** for global search on CERN GitLab.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--search-term` | string | Yes | - | Code/text to search for |
| `--project` | string | No | - | Limit to specific project |
| `--scope` | string | No | `blobs` | `blobs` (content) or `filenames` |
| `--ref` | string | No | - | Branch/tag to search within |
| `--page` | integer | No | `1` | Page number |
| `--per-page` | integer | No | `20` | Results count (max 100) |

**Output:**
```json
{
  "search_term": "RooFit",
  "scope": "blobs",
  "project": "(global)",
  "page": 1,
  "per_page": 20,
  "total_results": 15,
  "results": [
    {
      "file_name": "fitting.py",
      "file_path": "src/analysis/fitting.py",
      "project_id": 12345,
      "data": "import ROOT\nfrom ROOT import RooFit\n...",
      "ref": "main",
      "startline": 10
    }
  ]
}
```

---

### 7. search-lhcb-stack

Search for code within a specific LHCb software stack (e.g., `sim11`). Automatically resolves correct Git references using the LHCb nightly build API.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--search-term` | string | Yes | Code/text to search for |
| `--stack` | string | Yes | Stack name (e.g., `sim11`) |
| `--project` | string | No | Limit to specific project |
| `--scope` | string | No | `blobs` or `filenames` |
| `--ref` | string | No | Override automatic ref resolution |
| `--page` | integer | No | Page number |
| `--per-page` | integer | No | Results count |

**Output:** Same format as `search-code`, with automatically resolved branch references.

---

### 8. search-issues

Search for issues and discussions in a project.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--search-term` | string | Yes | - | Keywords to search for |
| `--project` | string | No | - | Limit to specific project |
| `--state` | string | No | `opened` | `opened`, `closed`, or `all` |
| `--per-page` | integer | No | `10` | Results count |

**Output:**
```json
[
  {
    "id": 123,
    "iid": 45,
    "project_id": 67890,
    "title": "Issue title",
    "description": "Issue description...",
    "state": "opened",
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-03-05T14:30:00Z",
    "web_url": "https://gitlab.cern.ch/group/project/-/issues/45"
  }
]
```

---

### 9. get-wiki

Access project wiki pages. **Requires authentication.**

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--project` | string | Yes | Project ID or path |
| `--page-slug` | string | No | Specific page slug (omit to list all pages) |

**Output (list mode):**
```json
[{"slug": "home", "title": "Home", "url": "https://gitlab.cern.ch/group/project/-/wikis/home"}]
```

**Output (specific page):**
```json
{"slug": "installation", "title": "Installation Guide", "content": "# Installation\n\nSteps..."}
```

---

### 10. inspect-project

Comprehensive analysis of a project's structure, build system, dependencies, and CI/CD configuration. This is the most informative single command for understanding a project.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--project` | string | Yes | Project ID or path |
| `--ref` | string | No | Branch/tag/commit |

**Output:**
```json
{
  "project": "lhcb/allen",
  "ref": "main",
  "ecosystems": ["python", "cpp"],
  "build_systems": ["cmake", "python-build"],
  "dependencies": [
    {
      "source_file": "requirements.txt",
      "ecosystem": "python",
      "count": 15,
      "items": [
        {"name": "numpy", "version_spec": ">=1.20"},
        {"name": "scipy", "version_spec": ""}
      ]
    }
  ],
  "ci_config": {
    "found": true,
    "analysis": {
      "stages": ["build", "test", "deploy"],
      "jobs": ["build_linux", "test_unit", "deploy_prod"],
      "image": "python:3.11"
    },
    "raw_preview": "stages:\n  - build\n  - test..."
  },
  "files_analyzed": 8
}
```

---

### 11. list-releases

List releases for a project.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--project` | string | Yes | - | Project ID or path |
| `--per-page` | integer | No | `20` | Results count |

**Output:**
```json
[
  {
    "tag_name": "v1.2.0",
    "name": "Release 1.2.0",
    "description": "Release notes...",
    "created_at": "2025-02-15T10:00:00Z",
    "published_at": "2025-02-15T12:00:00Z",
    "web_url": "https://gitlab.cern.ch/group/project/-/releases/v1.2.0"
  }
]
```

---

### 12. get-release

Get detailed information about a specific release.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--project` | string | Yes | Project ID or path |
| `--tag-name` | string | Yes | Release tag (e.g., `v1.0.0`) |

**Output:** Same as `list-releases` entry, plus `assets` array:
```json
{"assets": [{"name": "source.tar.gz", "url": "..."}]}
```

---

### 13. list-tags

List project tags with optional filtering.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--project` | string | Yes | - | Project ID or path |
| `--search` | string | No | - | Filter by name prefix |
| `--sort` | string | No | `desc` | `asc` or `desc` |
| `--per-page` | integer | No | `20` | Results count |

**Output:**
```json
[
  {
    "name": "v1.2.0",
    "message": "Release 1.2.0",
    "target": "main",
    "commit": {
      "id": "abc123...",
      "short_id": "abc123",
      "created_at": "2025-02-15T10:00:00Z"
    }
  }
]
```

---

### 14. test-connection

Test connectivity to the CERN GitLab instance. Takes no parameters.

**Output:**
```json
{
  "status": "connected",
  "gitlab_url": "https://gitlab.cern.ch",
  "authenticated": true,
  "version": "16.0.0",
  "revision": "abc123",
  "public_access": true
}
```

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

cerngitlab-cli

Directory Structure

SKILL.md

Report

Notice