GitLab Analyzer CLI & AI Failure Troubleshooting

A Python CLI tool that integrates with the GitLab REST API to inspect projects, pipelines, jobs, and trace logs, featuring AI-powered pipeline failure analysis via local Ollama LLMs.

---

Features

• GitLab Authentication: Secure connection via personal access token (PRIVATE-TOKEN), managed strictly through environment variables.
• Project Information: Retrieve project name, ID, default branch, and web URL.
• Pipeline Monitoring: Query the latest pipeline status, branch, commit SHA, and duration.
• Job Status & Log Inspection: View stages, duration, and status for pipeline jobs, identify failed jobs, and display latest log lines.
• Pipeline History & Statistics: Inspect recent pipelines with calculated success vs. failure rates.
• Ollama AI Integration: Ask questions about pipeline status (e.g. "What happened with the latest pipeline?") to analyze failed job traces, diagnose root causes, and provide actionable troubleshooting suggestions. Includes intelligent offline fallback diagnostics.
• Robust Error Handling & Logging: Python standard logging with configurable log levels, handling network timeouts, connection issues, HTTP 401/403/404 errors, and invalid inputs.
• Unit Testing: Comprehensive pytest test suite with 100% mocked GitLab API endpoints and zero live server dependencies.

---

Installation & Setup

1. Clone & Setup Virtual Environment

cd gitlab-analyzer
python -m venv .venv

# On Windows (PowerShell):
.\.venv\Scripts\Activate.ps1

# On Linux / macOS:
source .venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Copy .env.example to .env and fill in your GitLab credentials:

cp .env.example .env

Configuration keys:

Variable	Description	Default
GITLAB_URL	Base URL of your GitLab instance	https://gitlab.com
GITLAB_TOKEN	GitLab Personal Access Token with read_api scope	Required
GITLAB_PROJECT_ID	Numerical Project ID or URL-encoded path	Required
GITLAB_BRANCH	Target branch to analyze	main
OLLAMA_URL	Base URL of local Ollama server	http://localhost:11434
OLLAMA_MODEL	Ollama model name for AI diagnostics	llama3.2
LOG_LEVEL	Python logging level (INFO, DEBUG, WARNING, ERROR)	INFO

---

CLI Usage

Available Commands

Command	Description	Example
project	Display project details	python gitlab_analyzer.py project
pipeline	Display latest pipeline & jobs	python gitlab_analyzer.py pipeline
jobs	Display jobs for latest or given pipeline	python gitlab_analyzer.py jobs [pipeline_id]
history	Display pipeline history & statistics	python gitlab_analyzer.py history [--limit 10]
logs	View logs of failed jobs or specific job	python gitlab_analyzer.py logs [job_id]
ask	Natural language query about pipeline	python gitlab_analyzer.py ask "What happened with the latest pipeline?"
analyze	AI failure analysis of a pipeline	python gitlab_analyzer.py analyze [pipeline_id]

Command Options

Global flags can be passed with any command:

• --branch <name>: Override branch for the query.
• --project-id <id>: Override project ID.
• -v, --verbose: Enable verbose DEBUG logging.

Examples

# 1. Project details
python gitlab_analyzer.py project

# 2. Latest pipeline & jobs
python gitlab_analyzer.py pipeline

# 3. Pipeline history (last 5 runs)
python gitlab_analyzer.py history --limit 5

# 4. View logs for a specific job ID
python gitlab_analyzer.py logs 15973069788 --tail 50

# 5. Ask what happened with the latest pipeline (Ollama AI)
python gitlab_analyzer.py ask "What happened with the latest pipeline?"

# 6. Analyze a specific failed pipeline
python gitlab_analyzer.py analyze 2771178760

---

Ollama AI Integration

When analyzing failed pipelines, GitLab Analyzer extracts failed job traces and prompts a local Ollama model to explain the root cause and provide actionable troubleshooting steps.

Setting Up Ollama

1. Install Ollama from ollama.ai.
2. Start Ollama and pull your desired model:

   ollama serve
   ollama pull llama3.2

3. Run:

   python gitlab_analyzer.py ask "What happened with the latest pipeline?"

Note: If Ollama is not running, the tool automatically provides rule-based error diagnostics extracted from the job logs.

---

Running Unit Tests

All unit tests use pytest and mock GitLab API responses:

pytest -v test_gitlab_analyzer.py